Integrating USDC.n → USDC.inj Migration with the Skip API

GET /v2/info/chains?include_evm=true&include_svm=true&only_testnets=false
GET /v2/fungible/assets?include_evm_assets=true&include_cw20_assets=true&include_svm_assets=true&only_testnets=false

{
  "amount_in": "1000000",
  "source_asset_chain_id": "dydx-mainnet-1",
  "source_asset_denom": "ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5",
  "dest_asset_chain_id": "dydx-mainnet-1",
  "dest_asset_denom": "ibc/BDC8EC8C66D3D784B2DC7E8F7DAE93A49961AE747CEEBBC7DC4BAFF564E40BD3",
  "smart_relay": true,
  "experimental_features": ["stargate", "eureka", "layer_zero"],
  "allow_multi_tx": true,
  "allow_unsafe": true,
  "smart_swap_options": {
    "split_routes": true,
    "evm_swaps": true
  },
  "go_fast": true,
  "fast_transfer": true
}

{
  "amount_in": "1000000",
  "amount_out": "999200",
  "source_asset_chain_id": "dydx-mainnet-1",
  "source_asset_denom": "ibc/8E27BA2D...",
  "dest_asset_chain_id": "dydx-mainnet-1",
  "dest_asset_denom": "ibc/BDC8EC8C...",
  "operations": ["... individual steps that make up the route (omitted) ..."],
  "required_chain_addresses": ["dydx-mainnet-1", "noble-1", "<transit_evm_chain_id>", "injective-1", "dydx-mainnet-1"],
  "txs_required": 2
}

const msgsRequest = {
  // ★ source/dest chain IDs, denoms, and amount_in come from the /route response —
  //   not from your original request.
  source_asset_denom: route.source_asset_denom,
  source_asset_chain_id: route.source_asset_chain_id,
  dest_asset_denom: route.dest_asset_denom,
  dest_asset_chain_id: route.dest_asset_chain_id,
  amount_in: route.amount_in,
  amount_out: route.amount_out,

  // the array assembled in 3.1, unchanged
  address_list: addressList,

  // operations passed through from the /route response, unmodified — never hand-edit this value
  operations: route.operations,

  // slippage tolerance (%). Use the default "1" (1%) for the migration flow.
  slippage_tolerance_percent: '1',

  // Affiliate fee configuration field. Not used in the migration flow, so pass an empty object.
  chain_ids_to_affiliates: {},
};

{
  "txs": [
    {
      "cosmos_tx": {
        "chain_id": "dydx-mainnet-1",
        "signer_address": "dydx1...",
        "msgs": [{ "msg_type_url": "/ibc.applications.transfer.v1.MsgTransfer", "msg": "{...}" }]
      }
    },
    {
      "cosmos_tx": {
        "chain_id": "injective-1",
        "signer_address": "inj1...",
        "msgs": [{ "msg_type_url": "/ibc.applications.transfer.v1.MsgTransfer", "msg": "{...}" }]
      }
    }
  ]
}

const currentTx = txs[i].cosmos_tx;

// 1) Convert each message from the msgs response into the EncodeObject({ typeUrl, value })
//    shape your wallet expects. toEncodeObject/safeJsonParse are out of scope for this guide —
//    implement them yourself (watch out for timeout_timestamp precision, see above).
const msgAnys = currentTx.msgs.map(({ msg_type_url, msg }) => toEncodeObject(msg_type_url, safeJsonParse(msg)));

// 2) msgAnys/currentTx alone aren't enough to build a SignDoc — account_number/sequence must
//    be fetched separately from that chain's account-query API (e.g. the LCD endpoint
//    /cosmos/auth/v1beta1/accounts/{address}), and the fee (denom/amount/gas limit) must be
//    decided separately too. Both are out of scope for this guide.
const accountInfo = await fetchAccountInfo(currentTx.chain_id, currentTx.signer_address); // account_number, sequence
const fee = getFeeFor(currentTx.chain_id); // denom, amount, gas limit

// 3) Keplr's signDirect performs "signing only" — it never broadcasts on its own.
//    (Don't use a high-level method like CosmJS's SigningStargateClient.signAndBroadcast,
//    which signs and broadcasts in one call — broadcasting must happen separately through the
//    Skip API in chapter 5.)
//    buildSignDoc (assembling TxBody/AuthInfo) is also out of scope — implement it yourself.
const { signed, signature } = await window.keplr.signDirect(
  currentTx.chain_id,
  currentTx.signer_address,
  buildSignDoc(msgAnys, accountInfo, fee),
);

// 4) Assemble the signed TxRaw from the result and base64-encode it.
//    encodeTxRawBase64 is also out of scope — implement it yourself.
const txRawBase64 = encodeTxRawBase64(signed, signature);

const submitRequest = {
  chain_id: currentTx.chain_id,
  tx: '<base64-encoded TxRaw>',
};

GET /v2/tx/status?chain_id=<chain_id>&tx_hash=<tx_hash>

tx[0] signed → submit → STATE_PENDING → (IBC/CCTP relay processing) → STATE_COMPLETED_SUCCESS
  ↓
tx[1] signed → submit → STATE_PENDING → ... → STATE_COMPLETED_SUCCESS

const BASE_URL = 'https://go.skip.build/api/skip';

// 1) Confirm chains/assets — never hardcode, always resolve via the API.
const chainsRes = await fetch(`${BASE_URL}/v2/info/chains?include_evm=true&include_svm=true&only_testnets=false`);
const { chains } = await chainsRes.json();

const assetsRes = await fetch(
  `${BASE_URL}/v2/fungible/assets?include_evm_assets=true&include_cw20_assets=true&include_svm_assets=true&only_testnets=false`,
);
// Response shape: { chain_to_assets_map: { [chain_id]: { assets: [{ denom, origin_chain_id, origin_denom, ... }] } } }
const { chain_to_assets_map } = await assetsRes.json();

function assertChainSupported(chainId: string) {
  if (!chains.some((c) => c.chain_id === chainId)) {
    throw new Error(`"${chainId}" is not a chain_id present in /v2/info/chains.`);
  }
}

// Don't tell USDC.n and USDC.inj apart by symbol — distinguish them by which chain/denom the
// asset was originally issued on (origin_chain_id/origin_denom). USDC.n's origin is Noble's
// (noble-1) uusdc; USDC.inj's origin is the USDC minted on Injective (injective-1) via CCTP v2.
function findDenomByOrigin(chainId: string, originChainId: string, originDenom: string): string {
  const asset = chain_to_assets_map[chainId]?.assets.find(
    (a) => a.origin_chain_id === originChainId && a.origin_denom === originDenom,
  );
  if (!asset) {
    throw new Error(`Could not find an asset on "${chainId}" with origin (${originChainId}, ${originDenom}).`);
  }
  return asset.denom;
}

const sourceChainId = 'dydx-mainnet-1';
const destChainId = 'dydx-mainnet-1';
assertChainSupported(sourceChainId);
assertChainSupported(destChainId);

const sourceDenom = findDenomByOrigin(sourceChainId, 'noble-1', 'uusdc'); // USDC.n
const destDenom = findDenomByOrigin(destChainId, 'injective-1', 'erc20:0xa00C59fF5a080D2b954d0c75e46E22a0c371235a'); // USDC.inj

// 2) Request a route
const routeRes = await fetch(`${BASE_URL}/v2/fungible/route`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    amount_in: '1000000',
    source_asset_chain_id: sourceChainId,
    source_asset_denom: sourceDenom,
    dest_asset_chain_id: destChainId,
    dest_asset_denom: destDenom,
    smart_relay: true,
    experimental_features: ['stargate', 'eureka', 'layer_zero'],
    allow_multi_tx: true,
    allow_unsafe: true,
    smart_swap_options: { split_routes: true, evm_swaps: true },
    go_fast: true,
    fast_transfer: true,
  }),
});
// Error handling for routeRes.ok etc. is omitted here — a real implementation must handle it properly.
const route = await routeRes.json();
// Check whether operations actually contains a CCTP leg — a swap route can be selected even with
// this payload, so this check is the only way to tell whether it's the migration route
// (see chapter 2). assertRouteContainsCctp is out of scope — implement it yourself.
assertRouteContainsCctp(route.operations);

// 3) Build address_list — exactly in required_chain_addresses order, with no slot skipped.
// getUserAddressFor (how you obtain each chain's user address) is out of scope — implement it
// yourself (see chapter 0).
const addressList = route.required_chain_addresses.map((chainId) => getUserAddressFor(chainId));

// 4) Generate the transactions to sign — source/dest/amount_in/amount_out/operations come from the route response
const msgsRes = await fetch(`${BASE_URL}/v2/fungible/msgs`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    source_asset_denom: route.source_asset_denom,
    source_asset_chain_id: route.source_asset_chain_id,
    dest_asset_denom: route.dest_asset_denom,
    dest_asset_chain_id: route.dest_asset_chain_id,
    amount_in: route.amount_in,
    amount_out: route.amount_out,
    address_list: addressList,
    operations: route.operations,
    slippage_tolerance_percent: '1',
    chain_ids_to_affiliates: {},
  }),
});
const msgsResponse = await msgsRes.json();

// 5) Process each tx in order: sign → submit → confirm status
for (const { cosmos_tx: currentTx } of msgsResponse.txs) {
  // 5-1) Sign — delegate to a wallet (4.1) or sign directly (4.2). signCosmosTx is out of
  // scope — implement it yourself. The result is a base64 TxRaw.
  const txRawBase64 = await signCosmosTx(currentTx);

  // 5-2) Broadcasting must go only through /v2/tx/submit. Error handling for network errors,
  // 4xx/5xx responses, etc. is omitted here — a real implementation must handle it properly.
  const submitRes = await fetch(`${BASE_URL}/v2/tx/submit`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ chain_id: currentTx.chain_id, tx: txRawBase64 }),
  });
  const { tx_hash } = await submitRes.json();

  // 5-3) Poll until complete — judge by an exact string comparison on transfers[0].state.
  // The while(true) below is a simplification for explanatory purposes — a real implementation
  // should cap the number of retries/timeout.
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/v2/tx/status?chain_id=${currentTx.chain_id}&tx_hash=${tx_hash}`);
    const status = await statusRes.json();
    const state = status.transfers?.[0]?.state;

    if (['STATE_COMPLETED_ERROR', 'STATE_ABANDONED', 'STATE_PENDING_ERROR'].includes(state)) {
      throw new Error(`tx ${tx_hash} failed: ${state}`);
    }
    if (state === 'STATE_COMPLETED_SUCCESS') {
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, 4000)); // re-check every 3–5 seconds
  }

  // Move on to the next tx — if this was an Injective-signed tx, also confirm Skip Gas
  // Station's automatic INJ top-up landed (chapter 7).
}

// 6) All txs complete — migration done.