Skip to main content

Quickstart

Every operation is a JSON POST to https://agent.uswap.net/v1/OPERATION. HTTP and MCP use the same names and inputs.

1. Save a session​

curl https://agent.uswap.net/v1/session \
  -H 'Content-Type: application/json' \
  -d '{}'

Save the returned token in your secret store. Send it as Authorization: Bearer <token> on subsequent requests. You can reuse the session for multiple orders.

2. Discover both assets​

curl https://agent.uswap.net/v1/catalog \
  -H 'Content-Type: application/json' \
  -d '{"side":"from","query":"USDT"}'

For a category, call catalog again with its page_token. Continue until the response contains a selectable asset_id. Choose the correct network. Repeat with side: "to" for the destination.

Read the amount limits and recipient requirements on each asset. Use the returned IDs exactly. A ticker alone doesn't identify a network or product.

3. Quote​

{
  "source": "<source asset_id from catalog>",
  "destination": "<destination asset_id from catalog>",
  "amount": "20",
  "amount_side": "from",
  "recipient": "<destination address>"
}

Send this body to /v1/quote with your session token. amount: "20" means 20 units of the source asset. To specify the amount you want to receive, use amount_side: "to".

Check the returned amounts, expiry and costs against your spending policy. Convert raw integer amounts to display units using the asset's decimals. Keep calculations in integers or a decimal library.

4. Create the order​

Send to /v1/orders:

{
  "quote_id": "<quote_id>",
  "idempotency_key": "<unique key saved for this request>"
}

Save the operation_id and order_id. A succeeded operation means the order was created. It does not mean the swap has completed.

5. Fund and follow​

Call /v1/order with {"order_id":"<order_id>"}. A send_deposit action contains the current address, network, amount and any memo or tag. Use all of them.

Before sending, check your wallet's transaction journal for this order. Save the transaction hash as soon as the wallet broadcasts it. Never resend because deposit detection is taking time.

Call order at the interval in next_actions, normally 10 seconds. You can also submit the transaction hash with the notify_deposit action. This is a detection hint, not proof of payment.

The order shows each intent's progress and delivery evidence. terminal: true means tracking can stop. Check the result: expired, canceled and refunded orders are also terminal.

For a delivered product, use delivery with its order_id and intent_id to retrieve codes or credentials. Some products continue in the app.

Read the retry rules before putting this flow into production.