Getting Started with the Tychi SDK: Your First ugf.execute()

This is the shortest path from npm install to a working cross-chain transaction using the Tychi SDK. By the end of the post you will have a script that takes USDC from a wallet on Base and executes an action on BNB Chain — without holding any BNB native gas.

If you want the full reference, the docs have it. This post is the practical version.

What you need before starting

• Node 18 or newer.
• A funded wallet on Base with at least 5 USDC for testing.
• A second wallet (or the same one) on the destination chain you want to execute on. The signer can be the same in most cases.
• A code editor.

Step 1: Install

npm install @tychilabs/ugf-sdk

# Peer deps — only what you need for the chains you target
npm install ethers                   # EVM chains
npm install @solana/web3.js          # Solana
npm install @mysten/sui              # Sui

The SDK is small and tree-shakeable. Install the peer dependency for whichever destination chain family you plan to use.

Step 2: Authenticate

import { UGFClient } from "@tychilabs/ugf-sdk";
import { ethers } from "ethers";

const client = new UGFClient({
  baseUrl: "https://gateway.universalgasframework.com",
});

const provider = new ethers.JsonRpcProvider(BASE_RPC);
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

await client.auth.login(wallet);

client.auth.login issues a session against the user's signer. The session is required for the gateway to correlate later payment and execution calls. Tychi never holds the key — the signer stays in your control.

Step 3: Get a quote

const quote = await client.quote.get({
  payment_coin: "USDC",
  payer_address: wallet.address,
  payment_chain: "8453",        // Base
  payment_chain_type: "evm",
  tx_object: JSON.stringify({ from, to, data, value }),
  dest_chain_id: "56",          // BNB Chain
  dest_chain_type: "evm",
});

A few things worth noting:

• tx_object is the transaction you want to land on the destination chain. Same shape as a normal eth_sendTransaction payload.
• The quote is time-bounded. It carries an expiry. If you sit on it too long, it becomes invalid and you have to re-quote.
• The quote is signed by the gateway. The user signs the payment leg in the next step.

Step 4: Route the payment via x402

await client.payment.x402.execute({
  quote,
  signer: wallet,
  token: "USDC",
});

This settles the source-chain payment using the x402 protocol. USDC moves from the user's wallet to the Tychi vault on Base. The gateway sees the payment, validates it against the quote, and authorizes the destination relayer.

Step 5: Complete the destination action

const destProvider = new ethers.JsonRpcProvider(BNB_RPC);

await client.chains.evm.execute({
  quote,
  signer: wallet.connect(destProvider),
});

The relayer executes the user's tx_object on BNB Chain using its native gas reserve. The user pays nothing in BNB. From the user's perspective, the action has landed.

Putting it together

The full flow as one script:

const client = new UGFClient({ baseUrl: "https://gateway.universalgasframework.com" });
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

await client.auth.login(wallet);

const quote = await client.quote.get({
  payment_coin: "USDC",
  payer_address: wallet.address,
  payment_chain: "8453",
  payment_chain_type: "evm",
  tx_object: JSON.stringify(myTx),
  dest_chain_id: "56",
  dest_chain_type: "evm",
});

await client.payment.x402.execute({ quote, signer: wallet, token: "USDC" });
await client.chains.evm.execute({ quote, signer: wallet.connect(destProvider) });

That is the entire integration surface for an EVM-to-EVM cross-chain action.

Going non-EVM

For Solana and Sui, the destination call differs slightly. Solana uses client.chains.sol.sponsorCustomTx. Sui uses client.chains.sui.execute. The SDK abstracts the chain-family details, but the destination-side build still uses the chain's own SDK (@solana/web3.js, @mysten/sui). See the docs for full examples.

Common pitfalls

• Quote expired. If the user signed too late, re-quote. Never reuse an expired quote.
• Wrong tx_object encoding. Stringify with JSON.stringify. The gateway parses it strictly.
• Insufficient USDC on the source chain. The payment leg fails before anything else runs. Check balance first.
• Destination chain reverted. UGF refunds the payment leg automatically. Check the gateway logs to see why the destination call failed.

Where to go next

• Run the full example on testnet first using @tychilabs/ugf-testnet-js.
• Read the API reference for every method.
• Drop into the Telegram for help while integrating.

The SDK is designed to be readable. If something feels harder than it should be, tell us — that is signal we need to fix the API, not the docs.