Skip to main content

Swap quickstart

A swap is a durable order, not a one-off exchange call. Discover the live asset catalog, quote the requested route, create the order, then track the order until it reaches a terminal state.

1. Discover supported assets​

Start from the compact live asset catalog. It returns each currently available chain once, the chain IDs allowed in each direction, and a small featured-token set.

curl https://api-beta.wagyu.xyz/v2/swaps/assets

Fetch a bounded token page for the selected direction and chain. Use the returned token identifier and decimals in later requests.

curl 'https://api-beta.wagyu.xyz/v2/swaps/assets/tokens?direction=from&chainId=<source-chain-id>&limit=100'

The token route also accepts q, offset, and a maximum limit of 100. Use these live discovery responses rather than hard-coding an asset as available because it appeared earlier. A quote remains authoritative for whether the selected pair currently has a route: a pair we support but cannot route at this amount answers 400 with code: "no_route", while a chain that is currently switched off answers 503 with code: "unavailable". Only the second is worth retrying unchanged.

2. Ask for a quote​

For an exact-input route, call POST /v2/swaps/quote. Send fromAmount as a decimal string in the source asset's atomic unit.

curl --request POST https://api-beta.wagyu.xyz/v2/swaps/quote \
  --header 'content-type: application/json' \
  --data '{
    "fromChainId": <source-chain-id>,
    "toChainId": <destination-chain-id>,
    "fromToken": "<source-token>",
    "toToken": "<destination-token>",
    "fromAmount": "<atomic-source-amount>",
    "toAddress": "<recipient-address>"
  }'

The response always contains toAmount and may include output, fee, route, timing, and integrator details. For an exact destination amount, use the same endpoint with toAmount instead of fromAmount. A quote is an estimate, not the later funding instruction.

3. Create the durable order​

Submit the same route inputs plus the recipient address to POST /v2/swaps. Omit sessionId in a normal consumer flow: Core creates an owner session and returns it with the order.

curl --request POST https://api-beta.wagyu.xyz/v2/swaps \
  --header 'content-type: application/json' \
  --data '{
    "fromChainId": <source-chain-id>,
    "toChainId": <destination-chain-id>,
    "fromToken": "<source-token>",
    "toToken": "<destination-token>",
    "fromAmount": "<atomic-source-amount>",
    "toAddress": "<recipient-address>"
  }'

The created order provides the deposit address, deposit amount, initial status, orderId, and sessionId. Present the funding values exactly; do not derive them yourself. Persist the returned sessionId as an ownership credential and never put it in a shareable URL. An integrator may deliberately supply a valid sessionId to group its own orders only with a valid integrator API key; it is not an idempotency key.

Do not blindly retry a creation request after a network timeout: a second POST can create another order. See actions and retries for the current retry contract.

Integrating for your own users

Every request on this page works without a credential — but then it is anonymous: nothing attributes the order to your integration and no fee is paid to you. Send x-integrator-key: wg_... on the quote and the create to be credited. See integrator key for the per-request fee override, the payout addresses, and the reporting routes.

Optional card funding​

A client with a compatible provider adapter may offer card funding. Today the only documented provider is privy, and it is valid only for a USDC-on-Arbitrum source. Send fundingProvider: "privy" only for that path; otherwise omit it. Order creation remains authoritative.

4. Track it to a terminal state​

An orderId alone does not authorize a read. Read as the owner with the returned session in the x-session-id header:

curl https://api-beta.wagyu.xyz/v2/swaps/<order-id> \
  --header 'x-session-id: <returned-session-id>'

For read-only access to one order, a client may instead send the exact recipient address as ?verify=<recipient-address>. That route cannot submit refunds, make coinflip decisions, or modify the order. The order read routes deliberately use the same 404 response for a missing order and an invalid or absent credential; do not use a failed read as an existence check. See live updates for the optional WebSocket accelerator.

See order lifecycle for status meanings, ownership credentials, and the refund path.

Exact types are live

The interactive reference shows the generated request and response schemas for every supported consumer HTTP operation. Use it when implementing rather than copying examples from this page.