API Reference

The 7.Exchange production API is ready for swap integrations. Discover assets and providers, request quotes, lock a route, execute it, and track the resulting transaction.

Base URL


https://api.7.exchange/api/v1

Public swap integration endpoints do not require an API key unless an endpoint explicitly says otherwise. There is no key-generation flow for integrators — see Affiliate referral codes if you need swap attribution.

Dev announcements Dev general chat SDK Widget

Quick Start

A complete swap, from quote to confirmation.

cURL


BASE="https://api.7.exchange/api/v1"
 
# 1. Request routes
QUOTE=$(curl -s "$BASE/quote" -H "Content-Type: application/json" -d '{
  "srcChain": "ethereum",
  "srcAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "dstChain": "arbitrum",
  "dstAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "amount": "50",
  "slippage": 100,
  "depositor": "0xYourSourceWallet",
  "recipient": "0xYourDestinationWallet"
}')
 
PROVIDER=$(echo "$QUOTE" | jq -r '.data[0].provider')
ROUTE_ID=$(echo "$QUOTE" | jq -r '.data[0].routeId')
 
# 2. Lock the selected route
LOCK=$(curl -s "$BASE/quote/lock" -H "Content-Type: application/json" -d "{
  \"srcChain\": \"ethereum\",
  \"srcAddress\": \"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\",
  \"dstChain\": \"arbitrum\",
  \"dstAddress\": \"0xaf88d065e77c8cC2239327C5EDb3A432268e5831\",
  \"amount\": \"50\",
  \"slippage\": 100,
  \"provider\": \"$PROVIDER\",
  \"routeId\": \"$ROUTE_ID\",
  \"depositor\": \"0xYourSourceWallet\",
  \"recipient\": \"0xYourDestinationWallet\"
}")
 
LOCK_ID=$(echo "$LOCK" | jq -r '.data.lockId')
 
# 3. Execute
EXEC=$(curl -s "$BASE/quote/execute" -H "Content-Type: application/json" \
  -d "{\"lockId\": \"$LOCK_ID\"}")
 
TX_ID=$(echo "$EXEC" | jq -r '.data.transaction.id')
 
# 4. Poll until final
while true; do
  S=$(curl -s "$BASE/transaction/status?transactionId=$TX_ID")
  echo "$S" | jq -r '.data.transaction.status'
  [ "$(echo "$S" | jq -r '.data.final')" = "true" ] && break
  sleep 3
done

Integration Flow

Fetch chains

GET /api/v1/swap/chains — use each chain’s key as srcChain / dstChain.

Fetch assets

GET /api/v1/swap/assets — use each asset’s address as srcAddress / dstAddress.

Fetch routing providers

GET /api/v1/swap/sources — optional; quote responses already name their provider.

Request routes

POST /api/v1/quote — returns every available route for the pair and amount.

Lock the selected route

POST /api/v1/quote/lock — returns a short-lived lockId.

Execute

POST /api/v1/quote/execute — returns a transaction.id and, for client-side routes, an exec payload.

Track (client-side execution only)

POST /api/v1/transaction/track — send the public transaction.id and the wallet or deposit hash your client received.

Poll status

GET /api/v1/transaction/status — until final is true.

Read history

GET /api/v1/transaction/history — scoped by wallet address.

Steps 1–3 are cacheable. Only refetch chains and assets periodically — both responses flag recently added entries with new: true.

Conventions

Versioning

The current API version is v1. Every versioned response includes:


X-API-Version: 1
X-Request-Id: req_...

Change type	Ships in	Examples
Non-breaking	Same version	Adding a field, adding an enum value, adding an optional request parameter, adding metadata
Breaking	New path version	Removing or renaming a field, changing a field type, changing required request fields, changing enum casing, changing the response envelope

Every changelog entry that affects the public API names the affected version.

Build clients that tolerate unknown fields. New fields and new enum values can appear within v1 without notice. Breaking changes are announced in #dev-announcements before they ship.

Response envelopes

Endpoint kind	Shape
List endpoints	`{ "data": [...], "pagination": { "page", "perPage", "total", "hasMore" } }`
Quote preview	`{ "data": [...] }` — no pagination; it’s a request-scoped route set, not a paginated resource
Single-resource and actions	`{ "data": { ... } }`
Errors	`{ "error": { ... } }`

Beyond the envelope:

JSON request and response fields use camelCase.
Amounts are strings unless the field is explicitly a count or a basis-point number.
Timestamps are ISO 8601 strings.
Quote preview and lock return public route data and a fees object. They never return execution payloads.
Execute may include provider-specific quote, exec, and providerResult objects. Nested quote snapshots use fees. Use exec only for wallet execution — it is not provider tracking state.
Treat returned asset addresses as canonical for their chain. Compare EVM addresses case-insensitively unless you checksum them first.

Request rules

Send JSON bodies with Content-Type: application/json.
Use the chain key from /swap/chains as srcChain and dstChain.
Use the asset address from /swap/assets as srcAddress and dstAddress.
Send amount as a positive human-readable token amount string.
Send slippage in basis points — 100 means 1%. Valid range 0–10000 inclusive.
Send the real source wallet as depositor and the real destination wallet as recipient when requesting and locking quotes.
Use routeId from quote preview when locking; use lockId from lock when executing.

Never hardcode provider names. Use the provider key returned by the selected quote — the routing set changes as providers are added, paused, or removed.

Rate limits

Rate-limited responses return 429 with code RATE_LIMITED and these headers:


Retry-After: 30
X-RateLimit-Limit: ...
X-RateLimit-Remaining: ...
X-RateLimit-Reset: ...

Respect Retry-After rather than retrying on a fixed interval.

Chains


GET /api/v1/swap/chains

Lists active supported chains. Each chain includes new, which is true when the chain was added less than three days ago.

Query parameters

Name	Type	Description
`page`	number	Page number. Defaults to `1`.
`perPage`	number	Results per page. Defaults to `100`, maximum `1000`.
`query`	string	Search across name, shortname, and key.
`type`	string	Network type filter: `EVM`, `COSMOS`, `UTXO`, or `OTHER`.

cURL


curl -s "https://api.7.exchange/api/v1/swap/chains?query=ethereum"

200 OK


{
  "data": [
    {
      "key": "ethereum",
      "name": "Ethereum",
      "shortname": "ETH",
      "chainId": 1,
      "image": "https://...",
      "type": "EVM",
      "active": true,
      "new": true
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 100,
    "total": 1,
    "hasMore": false
  }
}

Assets


GET /api/v1/swap/assets

Lists supported swap assets. Use the returned address in quote and lock requests. Each asset includes new, which is true when the asset was added less than three days ago.

Query parameters

Name	Type	Description
`page`	number	Page number. Defaults to `1`.
`perPage`	number	Results per page. Defaults to `100`, maximum `1000`.
`query`	string	Search across name, symbol, and address.
`chain`	string	Chain key from `GET /api/v1/swap/chains`.

cURL


curl -s "https://api.7.exchange/api/v1/swap/assets?chain=ethereum&query=usdc"

200 OK


{
  "data": [
    {
      "name": "USD Coin",
      "symbol": "USDC",
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "image": "https://...",
      "chain": "ethereum",
      "isNative": false,
      "new": true
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 100,
    "total": 1,
    "hasMore": false
  }
}

Sources


GET /api/v1/swap/sources

Lists active routing providers.

Query parameters

Name	Type	Description
`page`	number	Page number. Defaults to `1`.
`perPage`	number	Results per page. Defaults to `20`, maximum `300`.
`type`	string	Provider type: `BRIDGE`, `EXCHANGE`, or `SERVICE`.

cURL


curl -s "https://api.7.exchange/api/v1/swap/sources?type=BRIDGE"

200 OK


{
  "data": [
    {
      "key": "ACROSS_PROTOCOL",
      "name": "Across",
      "image": "https://...",
      "type": "BRIDGE",
      "active": true
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "hasMore": false
  }
}

Get Quotes


POST /api/v1/quote

Returns available routes for the requested pair and amount.

Body

Name	Required	Type	Description
`srcChain`	✅	string	Source chain key.
`srcAddress`	✅	string	Source asset address from the assets endpoint.
`dstChain`	✅	string	Destination chain key.
`dstAddress`	✅	string	Destination asset address from the assets endpoint.
`amount`	✅	string	Positive human-readable amount.
`slippage`	—	number	Slippage in basis points. Range `0`–`10000`.
`confidentiality`	—	`public` \| `basic`	NEAR Intents execution mode. `basic` requests confidential handling; `public` is the default. Ignored by other providers.
`depositor`	—	string	Source wallet address. Recommended for accurate routes.
`recipient`	—	string	Destination wallet address. Recommended for accurate routes.
`exclude`	—	string[]	Provider keys to exclude.

cURL


curl -s "https://api.7.exchange/api/v1/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "srcChain": "ethereum",
    "srcAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "dstChain": "arbitrum",
    "dstAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "amount": "50",
    "slippage": 100,
    "depositor": "0xYourSourceWallet",
    "recipient": "0xYourDestinationWallet"
  }'

200 OK


{
  "data": [
    {
      "provider": "ACROSS_PROTOCOL",
      "routeId": "provider-route-id",
      "src": { "formatted": "50", "currency": "USDC", "usd": "50" },
      "dst": { "formatted": "49.8", "currency": "USDC", "usd": "49.8" },
      "fees": {
        "total": { "usd": "0.20", "formatted": "$0.20" },
        "items": [
          {
            "type": "bridge_fee",
            "amount": "200000",
            "token": {
              "chainId": 42161,
              "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
              "symbol": "USDC",
              "decimals": 6
            },
            "amountUsd": "0.20",
            "description": "Bridge fee",
            "providerLabel": "Bridge fee",
            "chain": { "chainId": 42161, "name": "Arbitrum" }
          }
        ]
      },
      "estimatedTime": 120,
      "steps": [
        { "type": "bridge", "name": "Across", "image": "https://..." }
      ]
    }
  ]
}

Quote objects include provider-specific route fields but never execution payloads. Preserve the returned provider key and selected routeId until lock completes.

No route available is not an error. This endpoint returns 200 with { "data": [] }. Check for an empty array before reading data[0].

Confidential NEAR Intents routes

To request confidential handling for a NEAR Intents route, set confidentiality to basic when requesting routes, select the returned NEAR_INTENTS route, and send the same value when locking it. Omit the field or set it to public for standard execution.

Quote and lock fields


{
  "confidentiality": "basic",
  "provider": "NEAR_INTENTS"
}

basic requests confidential handling within NEAR Intents. The source-chain deposit and destination-chain payout remain external-chain transactions and may be publicly visible. advanced is not currently supported by this API.

Lock Quote


POST /api/v1/quote/lock

Locks one selected provider route and returns a short-lived lockId for execution.

Body

Send the same fields used for POST /api/v1/quote, plus:

Name	Required	Type	Description
`provider`	✅	string	Provider key from the selected quote.
`depositor`	✅	string	Source wallet address.
`recipient`	✅	string	Destination wallet address.
`routeId`	—	string	Route ID from the selected quote. Recommended when multiple routes are returned.
`referralCode`	—	string	Affiliate referral code from your 7.Exchange referral link.

depositor and recipient are required here even though they’re optional on quote preview. When using confidentiality: "basic", send the same value used for quote preview.

cURL


curl -s "https://api.7.exchange/api/v1/quote/lock" \
  -H "Content-Type: application/json" \
  -d '{
    "srcChain": "ethereum",
    "srcAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "dstChain": "arbitrum",
    "dstAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "amount": "50",
    "slippage": 100,
    "provider": "ACROSS_PROTOCOL",
    "routeId": "provider-route-id",
    "depositor": "0xYourSourceWallet",
    "recipient": "0xYourDestinationWallet",
    "referralCode": "your-referral-code"
  }'

The response may include refreshed route amounts, fee data, expiry data, and provider display fields. It does not include wallet execution payloads.

200 OK


{
  "data": {
    "provider": "ACROSS_PROTOCOL",
    "routeId": "provider-route-id",
    "lockId": "locked-quote-id",
    "expiresAt": "2026-06-30T00:01:00.000Z",
    "ttlMs": 60000,
    "src": { "formatted": "50", "currency": "USDC", "usd": "50" },
    "dst": { "formatted": "49.8", "currency": "USDC", "usd": "49.8" },
    "fees": {
      "total": { "usd": "0.20", "formatted": "$0.20" },
      "items": [
        {
          "type": "bridge_fee",
          "amount": "200000",
          "token": {
            "chainId": 42161,
            "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
            "symbol": "USDC",
            "decimals": 6
          },
          "amountUsd": "0.20",
          "description": "Bridge fee",
          "providerLabel": "Bridge fee",
          "chain": { "chainId": 42161, "name": "Arbitrum" }
        }
      ]
    }
  }
}

Locks expire. Use ttlMs / expiresAt to drive your UI, and re-lock rather than retrying execute — an expired or already-used lock returns 409 QUOTE_EXPIRED.

Execute Quote


POST /api/v1/quote/execute

Executes the locked quote. The backend reads the source chain, destination chain, amount, slippage, provider, depositor, and recipient from the server-side lock record — you only send the lockId.

Body

Name	Required	Type	Description
`lockId`	✅	string	Locked quote ID returned by `POST /api/v1/quote/lock`.
`referralCode`	—	string	Affiliate referral code. If omitted, the code stored on the lock is used.

cURL


curl -s "https://api.7.exchange/api/v1/quote/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "lockId": "locked-quote-id",
    "referralCode": "your-referral-code"
  }'

The response is provider-specific. When the backend can record the swap, it includes a transaction object with public transaction data. If exec includes wallet execution data, perform the wallet action and then call POST /api/v1/transaction/track with the resulting hash.

200 OK


{
  "data": {
    "provider": "ACROSS_PROTOCOL",
    "lockId": "locked-quote-id",
    "providerResult": {
      "txHash": "0xProviderOrDepositHash",
      "status": "PENDING"
    },
    "quote": {
      "src": { "formatted": "50", "currency": "USDC", "usd": "50" },
      "dst": { "formatted": "49.8", "currency": "USDC", "usd": "49.8" },
      "fees": {
        "total": { "usd": "0.20", "formatted": "$0.20" },
        "items": [
          {
            "type": "bridge_fee",
            "amount": "200000",
            "token": {
              "chainId": 42161,
              "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
              "symbol": "USDC",
              "decimals": 6
            },
            "amountUsd": "0.20",
            "description": "Bridge fee",
            "providerLabel": "Bridge fee"
          }
        ]
      },
      "steps": [
        { "type": "bridge", "name": "Across", "image": "https://..." }
      ]
    },
    "exec": {
      "chainId": 1,
      "providerTarget": "0x...",
      "providerCalldata": "0x...",
      "value": "0",
      "meta": { "providerQuoteId": "provider-quote-id" }
    },
    "transaction": {
      "id": "public-transaction-id",
      "status": "PENDING"
    }
  }
}

Transaction Status


GET /api/v1/transaction/status

Returns the current public status for a transaction. Use this for polling after execute. Accepts the public transaction id returned by execute, or any known transaction hash.

Query parameters

Name	Type	Description
`transactionId`	string	Public transaction ID returned as `transaction.id`. Required when `hash` is omitted.
`hash`	string	Transaction hash lookup. Searches `hash`, `inboundHash`, and `outboundHash`. Required when `transactionId` is omitted.

cURL


curl -s "https://api.7.exchange/api/v1/transaction/status?transactionId=public-transaction-id"

200 OK


{
  "data": {
    "transaction": {
      "id": "public-transaction-id",
      "hash": "0x...",
      "inboundHash": "0x...",
      "outboundHash": null,
      "provider": "ACROSS_PROTOCOL",
      "status": "PENDING",
      "srcAmount": "50",
      "dstAmount": "49.8",
      "walletAddress": "0xYourSourceWallet",
      "recipientWalletAddress": "0xYourDestinationWallet",
      "createdAt": "2026-06-30T00:00:00.000Z",
      "updatedAt": "2026-06-30T00:01:00.000Z",
      "fee": {
        "amount": "0.20",
        "amountUsd": 0.2,
        "currency": "USD",
        "details": {
          "total": { "usd": "0.20", "formatted": "$0.20" },
          "items": [
            {
              "type": "bridge_fee",
              "amount": "200000",
              "token": {
                "chainId": 42161,
                "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
                "symbol": "USDC",
                "decimals": 6
              },
              "amountUsd": "0.20",
              "description": "Bridge fee"
            }
          ]
        }
      },
      "srcAsset": {
        "id": 101,
        "symbol": "USDC",
        "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "image": "https://...",
        "chain": "ethereum"
      },
      "dstAsset": {
        "id": 202,
        "symbol": "USDC",
        "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "image": "https://...",
        "chain": "arbitrum"
      }
    },
    "final": false
  }
}

Status values

Status	`final`	Meaning
`PENDING`	`false`	In progress. Keep polling.
`SUCCESS`	`true`	Completed.
`FAILED`	`true`	Did not complete.
`REFUND`	`true`	Funds returned to the depositor.

Track Transaction


POST /api/v1/transaction/track

Starts or refreshes provider status tracking for a transaction already recorded by execute. Normal execute responses start tracking automatically when enough provider context is available.

Use this endpoint only when:

Your client performs a wallet transaction after execute and receives a hash.
The user manually sends a direct deposit and your client later learns the deposit hash.
You want to refresh backend-owned tracking for an already recorded transaction.

Never send provider metadata — provider key, request ID, channel ID, provider quote ID, chain ID, deposit address, or deposit memo. The backend stores provider tracking context during execute and ignores client-supplied provider metadata. Never ask users or integrators to supply these values either; they are backend-owned execution context.

Body

Name	Required	Type	Description
`transactionId`	✅	string	Public transaction ID returned as `transaction.id`.
`txHash`	—	string	Source, deposit, or inbound transaction hash. TON external-message BoCs are accepted when stored provider context is sufficient to resolve them.

cURL


curl -s "https://api.7.exchange/api/v1/transaction/track" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "public-transaction-id",
    "txHash": "0xDepositHash"
  }'

200 OK


{
  "data": {
    "transaction": {
      "id": "public-transaction-id",
      "hash": "0xDepositHash",
      "inboundHash": "0xDepositHash",
      "provider": "ACROSS_PROTOCOL",
      "status": "PENDING"
    },
    "final": false,
    "tracking": true
  }
}

Tracking by execution mode

Server-side execution

The backend records the provider reference and starts tracking during POST /api/v1/quote/execute. No track call is needed — poll GET /api/v1/transaction/status immediately.

Client-side wallet

Execute

Call POST /api/v1/quote/execute and read data.transaction.id.

Perform the wallet call

Execute the call described by data.exec, if one is present. If exec.allSteps is returned, execute the steps in order.

Report the hash

When the wallet returns an on-chain hash, call POST /api/v1/transaction/track with { "transactionId": "...", "txHash": "..." }.

Poll

GET /api/v1/transaction/status until final is true.

Manual deposit

Show deposit instructions

Render the deposit instructions returned by execute.

Wait for the hash

Wait for the user or wallet provider to return the deposit transaction hash.

Report the hash

Call POST /api/v1/transaction/track with the public transactionId and the deposit txHash.

Poll

GET /api/v1/transaction/status until final is true.

Signature-only

Some routes require an off-chain provider signature submission instead of a source-chain transaction. Submit the signature through the provider-specific endpoint documented in the execute payload flow, then poll transaction status.

If no transaction hash exists, do not invent one — txHash is optional.

Transaction History


GET /api/v1/transaction/history

Returns public transaction history. Pass wallet addresses to scope results.

Query parameters

Name	Type	Description
`addresses`	string \| string[]	Wallet address filter. Repeatable or comma-separated.
`page`	number	Page number.
`perPage`	number	Results per page. Defaults to `20`, maximum `50`.
`query`	string	Search term.
`referralCode`	string	Exact referral code filter.
`transactionId`	string	Public transaction ID filter.
`statuses`	string \| string[]	`SUCCESS`, `PENDING`, `FAILED`, or `REFUND`. Repeatable or comma-separated.
`finalizedOnly`	boolean	When `true`, only finalized transactions are returned.

cURL


curl -s "https://api.7.exchange/api/v1/transaction/history?addresses=0xYourWallet&perPage=20"

200 OK


{
  "data": [
    {
      "id": "public-transaction-id",
      "status": "PENDING",
      "provider": "ACROSS_PROTOCOL",
      "hash": "0x...",
      "inboundHash": "0x...",
      "outboundHash": null,
      "srcAmount": "50",
      "dstAmount": "49.8",
      "amountUsd": 50,
      "walletAddress": "0xYourSourceWallet",
      "recipientWalletAddress": "0xYourDestinationWallet",
      "createdAt": "2026-06-30T00:00:00.000Z",
      "fee": {
        "amount": "0.20",
        "amountUsd": 0.2,
        "currency": "USD",
        "details": {
          "total": { "usd": "0.20", "formatted": "$0.20" },
          "items": [
            {
              "type": "bridge_fee",
              "amount": "200000",
              "token": {
                "chainId": 42161,
                "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
                "symbol": "USDC",
                "decimals": 6
              },
              "amountUsd": "0.20",
              "description": "Bridge fee"
            }
          ]
        }
      },
      "srcAsset": {
        "id": 101,
        "symbol": "USDC",
        "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "image": "https://...",
        "chain": "ethereum"
      },
      "dstAsset": {
        "id": 202,
        "symbol": "USDC",
        "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "image": "https://...",
        "chain": "arbitrum"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "hasMore": false
  }
}

Schemas

Quote fees object

Quote preview, lock, and nested execute quote responses return a fees object.

Legacy quote-level fee and feeBreakdown fields are not returned on public quote responses. Use fees instead.

Field	Type	Description
`total`	object	Normalized total fee summary.
`items`	array	Normalized fee line items, each with a typed category and token identity when known.

fees.total:

Field	Type	Description
`usd`	string	Estimated total fee value in USD.
`formatted`	string	Human-readable total fee value.

fees.items[]:

Field	Type	Description
`type`	string	One of the fee item types.
`amount`	string	Token amount for this item. Use `token.decimals` for display. May be signed for rewards or rebates.
`token`	object	Token identity: `chainId`, `address`, `symbol`, `decimals`.
`amountUsd`	string	Estimated USD value when known.
`description`	string	Human-readable explanation from the backend or provider.
`providerLabel`	string	Original provider label, useful for debugging or display.
`chain`	object	Chain identity: `chainId`, sometimes `name`.

Fee item types

Type	Description
`source_gas`	Source-chain gas or network cost.
`destination_gas`	Destination-chain gas, outbound, or egress cost.
`liquidity_fee`	Liquidity provider, pool, or route liquidity fee.
`protocol_fee`	Provider or protocol service fee not more specifically classified.
`bridge_fee`	Bridge or relayer service fee for cross-chain transfer execution.
`integrator_fee`	Affiliate, broker, or integrator fee.
`swap_impact`	Price impact, spread, or market-depth value impact from a swap leg.
`route_loss`	Quote-level route value loss not exposed by the provider as a specific fee item.
`messaging_fee`	Cross-chain message delivery fee, such as a LayerZero messaging fee.
`boost_fee`	Optional speed, priority, or boost fee.
`gas_drop_fee`	Destination native-token gas drop sent to the recipient.
`cctp_fee`	Circle CCTP receive, attestation, or finality fee.
`transfer_fee`	Token or network transfer fee not captured by gas, bridge, or protocol categories.
`transfer_reward`	Reward, rebate, or negative fee that offsets route cost.
`other`	Provider fee item that cannot be classified into a known category.

New fee item types can be added within v1. Render unknown types using description and providerLabel rather than dropping them — that’s what other and the fallback fields are for.

Transaction fee object

Transaction status and history responses return a recorded fee object. It may be empty when a transaction has no recorded fee details.

Field	Type	Description
`amount`	string \| null	Recorded fee amount when known.
`amountUsd`	number \| null	Recorded fee value in USD when known.
`currency`	string \| null	Currency or token symbol for `amount`.
`details`	object \| array \| null	Recorded fee details. When populated from a quote, items use the `fees.items[]` shape.

Transaction asset object

Status and history responses include srcAsset and dstAsset snapshots, recorded when execute creates the transaction.

Field	Type	Description
`id`	number \| null	Internal asset ID.
`symbol`	string \| null	Token symbol.
`contract`	string \| null	Token contract address, or `null` for native assets.
`image`	string \| null	Token image URL.
`chain`	string \| null	Chain key.

Execute `exec` object

exec appears on execute responses when the selected route needs client-side wallet execution or exposes execution metadata. It is intentionally not returned by quote preview or lock.

Field	Type	Description
`chainId`	number \| null	Numeric source chain ID for wallet execution when applicable.
`providerTarget`	string	Contract, deposit, or provider target address for a wallet call.
`providerCalldata`	string	Hex calldata for EVM wallet execution.
`value`	string	Native token value to send, in base units.
`srcToken`	string	Source token address or `native`.
`srcAmount`	string	Source amount in base units.
`approvalTarget`	string	Token approval spender when an approval is required.
`approvalToken`	string	Token to approve when an approval is required.
`approvalAmount`	string	Approval amount in base units.
`allSteps`	array	Ordered provider execution steps. If present, execute them in order.
`meta`	object	Provider execution metadata — `providerQuoteId`, deposit address, channel ID, wallet execution data. Raw provider payloads and request params are not returned.

Never send exec.meta, provider IDs, request IDs, channel IDs, provider quote IDs, chain IDs, deposit addresses, or deposit memos back to POST /api/v1/transaction/track. The backend stores provider tracking context server-side during execute.

Provider-specific objects

Some execute response fields — especially providerResult and parts of quote — are provider-specific. Read only the fields you need and tolerate additional ones.

Object	Common fields	Notes
`providerResult`	`txHash`, `status`, `requestId`, `channelId`, `depositAddress`, `depositMemo`, `execution`	Shape depends on provider and execution mode. Never send these back to tracking.
`quote`	`src`, `dst`, `steps`, `fees`, `estimatedTime`	Stored route snapshot used for display and transaction recording.
`exec.meta`	`providerQuoteId`, `selectedQuoteId`, `executionMode`, `walletExecution`, `depositAddress`, `channelId`	Client wallet execution only. Raw provider payloads and original request params are stripped from public responses.

Errors

All failures use one envelope:

Error response


{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "amount must be a positive number string",
    "field": "amount",
    "requestId": "req_01H...",
    "details": {
      "errors": [
        {
          "code": "INVALID_AMOUNT",
          "field": "amount",
          "message": "amount must be a positive number string"
        }
      ]
    }
  }
}

Branch on error.code, never on error.message — messages are human-facing and can change without a version bump. When multiple validation errors are found, they’re all returned in error.details.errors.

Failure	Status	Code
Missing or invalid required field	`400`	`VALIDATION_ERROR`
Invalid amount	`400`	`INVALID_AMOUNT`
Invalid slippage	`400`	`INVALID_SLIPPAGE`
Invalid participant address	`400`	`INVALID_ADDRESS`
Same-chain same-asset swap	`400`	`UNSUPPORTED_PAIR`
Missing `provider` on lock	`400`	`MISSING_PROVIDER`
Missing `lockId` on execute	`400`	`MISSING_LOCK_ID`
Expired or already-used lock	`409`	`QUOTE_EXPIRED`
Provider unavailable for the selected route	`409` / `503`	`PROVIDER_UNAVAILABLE`
Rate limited	`429`	`RATE_LIMITED`
Backend error	`500`	`INTERNAL_ERROR`
Upstream / provider error	`502` / `503`	`BAD_GATEWAY` / `SERVICE_UNAVAILABLE`

Include error.requestId (or the X-Request-Id response header) when reporting a problem in #dev-general — it lets us trace the exact request.

Affiliate Referral Codes

There is no API-key generation flow for integrators. To attribute swaps:

Create an account

Open the affiliate dashboard

Complete the affiliate flow.

Create or copy a referral code

Your referral link contains the code.

Send it with lock and execute

Pass it as referralCode in POST /api/v1/quote/lock and POST /api/v1/quote/execute.

See the referral program for payout details.

Support

#dev-announcements — API changes & deprecations #dev-general — integration questions

Breaking changes are announced in #dev-announcements ahead of release. If you’re running an integration in production, subscribe to that channel — it’s the only place changes are communicated before they appear in the changelog.

API Reference

Quick Start

cURL

TypeScript

Integration Flow

Fetch chains

Fetch assets

Fetch routing providers

Request routes

Lock the selected route

Execute

Track (client-side execution only)

Poll status

Read history

Conventions

Versioning

Response envelopes

Request rules

Rate limits

Chains

Query parameters

cURL

TypeScript

Assets

Query parameters

cURL

TypeScript

Sources

Query parameters

cURL

TypeScript

Get Quotes

Body

cURL

TypeScript

Confidential NEAR Intents routes

Lock Quote

Body

cURL

TypeScript

Execute Quote

Body

cURL

TypeScript

Transaction Status

Query parameters

cURL

TypeScript

Status values

Track Transaction

Body

cURL

TypeScript

Tracking by execution mode

Server-side execution

Client-side wallet

Execute

Perform the wallet call

Report the hash

Poll

Manual deposit

Show deposit instructions

Wait for the hash

Report the hash

Poll

Signature-only

Transaction History

Query parameters

cURL

TypeScript

Schemas

Quote fees object

Fee item types

Transaction fee object

Transaction asset object

Execute exec object

Provider-specific objects

Errors

Affiliate Referral Codes

Create an account

Execute `exec` object