API Cookbook

const API_BASE = 'https://api.1tx.fi/api/v1';
const headers = { 'x-api-key': process.env['1TX_API_KEY']! };

type Bundle = {
  chainId: number;
  amountIn: string;
  expectedOut: string;
  minOut: string | null;
  expiresAt: number | null;
  quoteBlock: number;
  requires: { token: `0x${string}`; amount: string }[];
  leftovers: { token: `0x${string}`; maxAmount: string }[];
  calls: { to: `0x${string}`; data: `0x${string}`; value: string; type: string }[];
  simulation: { ok: true; gasUsed: string; tokenOutDelta: string; assumedBalances: boolean };
};

async function getBundle(path: string, params: Record<string, string>): Promise<Bundle> {
  const response = await fetch(`${API_BASE}${path}?${new URLSearchParams(params)}`, { headers });
  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    throw new Error(`${response.status}: ${body.message ?? response.statusText}`);
  }
  return response.json();
}

const query = new URLSearchParams({
  chainId: '8453',
  isStablecoin: 'true',
  enrich: 'true',
  tier: 'Core',
  maxCv: '0.2',
  minHistoryDays: '90',
  sortBy: 'apy',
  sortOrder: 'desc',
  limit: '5',
});

const { data: instruments } = await fetch(`${API_BASE}/instruments?${query}`, { headers })
  .then((response) => response.json());

const target = instruments[0];

import { parseUnits } from 'viem';

const bundle = await getBundle(`/instruments/${target.instrumentId}/calldata`, {
  action: 'deposit',
  account,
  amount: parseUnits('1000', 6).toString(),
});

for (const requirement of bundle.requires) {
  const balance = await publicClient.readContract({
    address: requirement.token,
    abi: erc20Abi,
    functionName: 'balanceOf',
    args: [account],
  });
  if (balance < BigInt(requirement.amount)) {
    throw new Error(`short ${requirement.token}: need ${requirement.amount}, have ${balance}`);
  }
}

const { id } = await wallet.sendCalls({
  account,
  calls: bundle.calls.map((call) => ({
    to: call.to,
    data: call.data,
    value: BigInt(call.value),
  })),
});

// Exact amount of the underlying asset:
const partial = await getBundle(`/instruments/${instrumentId}/calldata`, {
  action: 'withdraw',
  account,
  amount: parseUnits('250', 6).toString(),
});

// Or empty the position, shares and accrued interest included:
const full = await getBundle(`/instruments/${instrumentId}/calldata`, {
  action: 'withdraw',
  account,
  amount: 'max',
});

const bundle = await getBundle(`/instruments/${eurcInstrumentId}/calldata`, {
  action: 'deposit',
  account,
  amount: parseUnits('1000', 6).toString(),
  tokenIn: USDC_BASE,
  slippageBps: '50',
});

if (bundle.expiresAt && bundle.expiresAt * 1000 < Date.now() + 15_000) {
  throw new Error('quote too close to expiry; rebuild');
}

console.log('dust ceiling:', bundle.leftovers);

const exit = await getBundle(`/instruments/${from}/calldata`, {
  action: 'withdraw',
  account,
  amount: 'max',
});

await sendAndWait(exit);

// Size the entry on the realised proceeds, not on the exit's estimate.
const proceeds = await publicClient.readContract({
  address: underlying,
  abi: erc20Abi,
  functionName: 'balanceOf',
  args: [account],
});

const entry = await getBundle(`/instruments/${to}/calldata`, {
  action: 'deposit',
  account,
  amount: proceeds.toString(),
});

await sendAndWait(entry);

const burn = await getBundle('/bridge/calldata', {
  fromChainId: '8453',
  toChainId: '42161',
  amount: parseUnits('1000', 6).toString(),
  account,
  fast: 'true',
});

console.log('circle fee ceiling:', burn.maxFee, 'finality:', burn.minFinalityThreshold);
const sourceTxHash = await sendAndWait(burn);

const deposit = await getBundle(`/instruments/${arbitrumInstrumentId}/calldata`, {
  action: 'deposit',
  account,
  amount: mintedAmount.toString(), // what arrived, after Circle's fee
});

try {
  const bundle = await getBundle(path, params);
  await sendAndWait(bundle);
} catch (error) {
  // A refusal is a decision, not a transport failure. Log the message, do not blind-retry a 400.
  logger.warn({ path, params, error });
}