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.
https://api.7.exchange/api/v1Public 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.
Quick Start
Start with discovery and a quote preview. These examples do not lock a route, execute a swap, or send a wallet transaction. Replace the illustrative chain/asset identifiers with values returned by discovery for your chosen pair.
cURL
BASE="https://api.7.exchange/api/v1"
curl --fail-with-body "$BASE/swap/chains?query=ethereum"
curl --fail-with-body "$BASE/swap/assets?chain=ethereum&query=usdc"
curl --fail-with-body "$BASE/quote" \
-H "Content-Type: application/json" \
-d '{
"srcChain": "ethereum",
"srcAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"dstChain": "arbitrum-one",
"dstAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"amount": "50",
"slippage": 100
}'Use the selected provider and optional routeId to lock a quote
with the real source and destination wallet addresses. After confirmation,
execute once, handle the selected execution mode,
and report source hashes with the required tracking authorization.
The typed SDK implements the REST transport and observation;
the widget includes the wallet-enabled UI.
OpenAPI contract
Download the public swap OpenAPI 3.1 JSON. It describes the ten public operations wrapped by the SDK, including requests, response envelopes, and error schemas. Import it into an OpenAPI-compatible viewer or client generator. This download is a static contract; no hosted Swagger UI endpoint is provided.
The catalog and platform-statistics endpoints below are additional public REST operations and are outside the SDK’s current method set. Account, admin, and restricted provider-reference APIs are outside this guide.
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 — consumes the lock once and returns execution data.
Check that transaction was recorded before authorizing further wallet actions;
it can be null with transactionError.
Track (not needed)
Tracking starts at execute and the platform detects the source deposit itself. No
track call or transaction hash is needed; POST /api/v1/transaction/track is
deprecated.
Poll status
GET /api/v1/transaction/status — until final is true.
Read history
GET /api/v1/transaction/history — public platform history, optionally filtered
by wallet addresses.
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.
- Transaction timestamps are ISO 8601 strings. History/statistics
fromandto,exec.expiresAt, andX-RateLimit-Resetuse Unix seconds;ttlMsuses milliseconds. - Quote preview and lock return public route data and a
feesobject. They never return execution payloads. - Execute may include provider-specific
quote,exec, andproviderResultobjects. Nested quote snapshots usefees. Useexeconly 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
keyfrom/swap/chainsassrcChainanddstChain. - Use the asset
addressfrom/swap/assetsassrcAddressanddstAddress. - Send
amountas a positive human-readable token amount string. - Send
slippagein basis points —100means 1%. Valid range0–10000inclusive. - Send the real source wallet as
depositorand the real destination wallet asrecipientwhen requesting and locking quotes. - Use
routeIdfrom quote preview when locking; uselockIdfrom 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 for safe reads. Do not replay lock, execute, or signature
POSTs automatically, including after a timeout or 429.
X-RateLimit-Reset is Unix seconds.
Current application limits are per IP and can be combined with deployment-level limits:
| Scope | Application limit |
|---|---|
All /api/v1 requests | 100 per minute |
| History and platform statistics | 30 per minute |
| Transaction tracking | 5 per 5 minutes |
Response headers are authoritative for the request that was limited.
Browser access
Public access does not bypass browser CORS. To call the API directly from a browser, request approval for your exact origin in #dev-general ; otherwise, route requests through your own server. No API key is needed for the documented public swap operations. Hash submission has separate transaction-ownership requirements described under tracking. Proxies and network failures can produce non-JSON responses; handle those before assuming an API error envelope.
Chains
GET /api/v1/swap/chainsLists 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"{
"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/assetsLists 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"{
"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/sourcesLists active routing providers.
Query parameters
| Name | Type | Description |
|---|---|---|
page | number | Page number. Defaults to 1. |
perPage | number | Defaults to 100. Use 1–300; the source query caps results at 300 even if pagination echoes a larger requested value. |
type | string | Provider type: BRIDGE, EXCHANGE, or SERVICE. |
cURL
curl -s "https://api.7.exchange/api/v1/swap/sources?type=BRIDGE"{
"data": [
{
"key": "ACROSS_PROTOCOL",
"name": "Across",
"image": "https://...",
"type": "BRIDGE",
"active": true
}
],
"pagination": {
"page": 1,
"perPage": 100,
"total": 1,
"hasMore": false
}
}Integration Catalog
GET /api/v1/swap/integrationsReturns a display catalog of providers, chains, and wallets. Items contain name,
image, and type; use the chains/assets/sources endpoints for request identifiers.
The SDK does not currently wrap this endpoint.
| Name | Type | Description |
|---|---|---|
page | number | Defaults to 1. |
perPage | number | Defaults to 100; use 1–200 for consistent paging. The catalog query caps results at 200. |
query | string | Search display names and available keys/aliases. |
type | string | ALL (default), EXCHANGE, BRIDGE, SERVICE, CHAIN, or WALLET. |
The response is { data, pagination, meta: { counts } }. Counts include
exchanges, bridges, services, chains, and wallets; filtered categories
can report zero for unrelated categories.
curl -s "https://api.7.exchange/api/v1/swap/integrations?type=CHAIN&perPage=20"Get Quotes
POST /api/v1/quoteReturns 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. |
executionCapabilities | — | string[] | Optional client features (maximum 8 names). uniswapx-order-v1 opts into UniswapX gasless orders. Send on both preview and lock. |
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. |
referrer | — | string | Legacy provider referrer context; separate from affiliate referralCode. |
decimals | — | number | Compatibility input; source precision is resolved from backend asset metadata, not trusted from this value. |
cURL
curl -s "https://api.7.exchange/api/v1/quote" \
-H "Content-Type: application/json" \
-d '{
"srcChain": "ethereum",
"srcAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"dstChain": "arbitrum-one",
"dstAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"amount": "50",
"slippage": 100,
"depositor": "0xYourSourceWallet",
"recipient": "0xYourDestinationWallet"
}'{
"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.
{
"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/lockLocks 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. |
namespace | — | string | Optional wallet namespace metadata stored with the lock. |
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-one",
"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.
{
"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 are single-use. Use ttlMs / expiresAt when supplied; do not assume a
fixed lifetime. Execute consumes a lock before provider processing completes.
409 QUOTE_EXPIRED means expired or already consumed, and does not prove a
previous attempt failed. After an uncertain outcome, reconcile before creating
another lock or sending another transaction. Only start a fresh reviewed flow
once prior execution has been ruled out or resolved.
Execute Quote
POST /api/v1/quote/executeExecutes the locked quote. The backend reads the source chain, destination chain,
amount, slippage, provider, depositor, and recipient from the server-side lock
record. lockId is the only required field; an explicit referralCode can override
stored attribution. The lock ID is an execution capability, not wallet-session
authentication. Keep it private and never use it as a payment receipt.
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 and a transaction-bound
trackingToken. Interpret the selected execution mode before authorizing any
wallet action: exec is not always a single EVM call. The platform detects the
resulting deposit itself; trackingToken is needed only to submit a UniswapX order
signature. Neither HTTP 200 nor a recorded
transaction means the swap has settled.
{
"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"
},
"trackingToken": "execute-issued-tracking-capability"
}
}Execute can return transaction: null with transactionError even after provider
processing. Stop further wallet actions and reconcile. Do not hide this condition
behind an automatic new lock, retry, or fabricated transaction ID. Timeouts and
generic failures can likewise leave the outcome unknown.
Submit Signature
POST /api/v1/quote/submit-signatureSubmits off-chain signatures for Stargate and UniswapX execution flows. This operation does not connect a wallet or sign on the caller’s behalf.
Stargate. Use the provider quote ID from execute metadata, not the public
preview routeId or the single-use lockId.
| Name | Required | Type | Description |
|---|---|---|---|
provider | — | string | Defaults to STARGATE. |
providerQuoteId | ✅ | string | Execute-issued ID: 0x plus 64 hex digits, or quote_ followed by letters, digits, _, or -. |
signatures | ✅ | string[] | Non-empty list of hex signatures. Sign only the supported execute-issued payload after user review. |
{
"provider": "STARGATE",
"providerQuoteId": "quote_provider_reference",
"signatures": ["0x1234"]
}{
"data": {
"provider": "STARGATE",
"providerQuoteId": "quote_provider_reference",
"result": { "accepted": true }
}
}UniswapX. Submit the swapper’s EIP-712 signature of
providerResult.signTypedData before providerResult.deadline.
| Name | Required | Type | Description |
|---|---|---|---|
provider | ✅ | string | UNISWAPX. |
transactionId | ✅ | string | transaction.id returned by execute. |
trackingToken | ✅ | string | Private capability returned by execute. Never share or log it. |
signature | ✅ | string | 65-byte (or 64-byte compact) hex signature by the swapper. |
{
"data": {
"provider": "UNISWAPX",
"orderId": "0x94883b78891dd417eb834d9be15d1666569f0c0d2d96a72bcaa07cdea1ccbf7d",
"submissionState": "submitted",
"orderStatus": "open",
"transaction": { "id": "5a1d1a6e-9a3f-4f4b-9d2b-2b8c4d6e7f80", "status": "PENDING" }
}
}submissionState: "unknown" means the order service did not confirm acceptance.
Repeat the same request: the server checks the order service before sending the
same signed order again. A signature from another wallet returns
400 INVALID_SIGNATURE; a missing or invalid tracking token returns 403; a
passed deadline returns 409 ORDER_EXPIRED; a concurrent submission returns
409 SUBMISSION_IN_PROGRESS.
The Stargate result is provider-specific. Placeholder signatures above illustrate
the wire shape, not a usable signature. Missing/invalid fields return
400 VALIDATION_ERROR; an unavailable provider returns 503 PROVIDER_UNAVAILABLE.
Submit once and reconcile uncertain outcomes; a signature is not a source-chain
transaction hash.
Transaction Status
GET /api/v1/transaction/statusReturns 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 | Searches hash, inboundHash, and outboundHash. Required when transactionId is omitted; a non-empty hash takes precedence if both are supplied. Prefer one lookup identifier. |
cURL
curl -s "https://api.7.exchange/api/v1/transaction/status?transactionId=public-transaction-id"{
"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-one"
}
},
"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. |
EXPIRED | true | No deposit was made before the swap’s deadline. No funds moved. |
Track Transaction (deprecated)
POST /api/v1/transaction/trackDeprecated. Tracking starts automatically at execute, resumes after restarts, and
the platform detects each deposit itself. This endpoint only refreshes tracking for
an already recorded transaction and will be removed in a future version. Use
GET /transaction/status to observe a swap.
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 | Deprecated. Accepted for compatibility and ignored. |
trackingToken | — | string | Deprecated. Accepted for compatibility and ignored. |
cURL
curl -s "https://api.7.exchange/api/v1/transaction/track" \
-H "Content-Type: application/json" \
-d '{ "transactionId": "public-transaction-id" }'{
"data": {
"transaction": {
"id": "public-transaction-id",
"hash": null,
"inboundHash": null,
"provider": "ACROSS_PROTOCOL",
"status": "PENDING"
},
"final": false,
"tracking": true
}
}How deposits are detected
The platform finds each swap’s source deposit from the provider’s own record of
the execution it issued: the provider contract’s deposit event on the source
chain, the THORChain/MAYAChain indexer, or the provider’s status for its deposit
address, request, or order. Nothing a client submits is used, so track cannot
attach or change a hash. The transaction’s hash and inboundHash appear once the
deposit is detected.
For wallet-call routes, send the deposit from the depositor wallet given at lock,
using the call (or memo) returned by execute without changes. A deposit sent
another way, such as from a different wallet or through another interface, is not
attributed to the swap and it stays PENDING. Manual-deposit routes are detected
at their deposit address whichever wallet funds it.
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.
UniswapX gasless orders
Same-chain ERC-20 swaps can be routed as UniswapX orders. The user signs an off-chain Permit2 order; a filler pays the swap gas and settles it on-chain before the order deadline. An order that is not filled by its deadline expires without moving funds. Native-token input is not offered.
Opt in
Send executionCapabilities: ["uniswapx-order-v1"] on both quote and lock.
UNISWAPX routes are returned only to clients that send it.
Execute
Execute returns exec.meta.executionMode: "uniswapx-order" and a providerResult
with orderId, chainId, routing (DUTCH_V2 or DUTCH_V3), deadline (Unix
seconds), approvalTarget (the canonical Permit2 contract), approvalToken,
approvalAmount, and signTypedData (domain, types,
primaryType: "PermitWitnessTransferFrom", message).
Approve Permit2
Ensure the swapper’s ERC-20 allowance to approvalTarget is at least
approvalAmount. This is the only on-chain step. With an unlimited Permit2
approval it is needed once per token; every later spend still requires a new
order signature.
Sign
Check the order against the swap (swapper, input token and amount, recipient and
output), then sign signTypedData with the swapper wallet
(eth_signTypedData_v4).
Submit
Send the signature with POST /quote/submit-signature
before deadline. Never sign a second order for the same execution.
Poll
Poll GET /api/v1/transaction/status. The transaction succeeds when the order is
filled; the fill transaction hash then appears on the transaction. Expired,
cancelled or rejected orders, and orders never submitted before their deadline,
are FAILED and moved no funds.
Quotes report the signed starting output as dstAmount and the worst-case signed
output as minDstAmount, both net of the platform fee. The fee is an
integrator_fee item paid in the output token; there is no gas fee item.
Transaction History
GET /api/v1/transaction/historyReturns public platform transaction history when addresses is omitted; that
unfiltered feed lists finalized transactions only. Pass wallet addresses (or a
transactionId) to include in-flight records. Results are newest first and do
not require wallet login. Filtering by an address does not prove ownership.
Query parameters
| Name | Type | Description |
|---|---|---|
addresses | string | string[] | Wallet address filter. Repeatable or comma-separated; at most 25 distinct addresses. |
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, REFUND, or EXPIRED. Repeatable or comma-separated. |
finalizedOnly | boolean | When true, only finalized records are returned: SUCCESS, FAILED, or REFUND by default, intersected with statuses if supplied (request EXPIRED explicitly). |
from, to | number | Optional inclusive transaction creation-time bounds as non-negative Unix seconds. from must not exceed to. |
cURL
curl -s "https://api.7.exchange/api/v1/transaction/history?addresses=0xYourWallet&perPage=20"{
"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-one"
}
}
],
"pagination": {
"page": 1,
"perPage": 20,
"total": 1,
"hasMore": false
}
}Platform Statistics
GET /api/v1/transaction/statsReturns public aggregate statistics for recorded SUCCESS transactions. The SDK
does not currently wrap this endpoint.
| Name | Type | Description |
|---|---|---|
from, to | number | Optional inclusive transaction creation-time bounds as non-negative Unix seconds; from must not exceed to. |
curl -s "https://api.7.exchange/api/v1/transaction/stats"{
"data": {
"txCount": 123,
"totalVolumeUsd": 4567.89
}
}Both fields are numbers: txCount is the matching count and totalVolumeUsd is
the sum of recorded USD amounts. This is platform data, not a live provider quote.
Schemas
Quote fees object
Quote preview, lock, and non-empty nested execute quote responses return a fees
object. It can be empty when details are unavailable; total and items are not
guaranteed on every route. Missing estimates do not imply zero cost. An empty
nested execute quote can remain {}.
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 | Base-unit 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. |
expiresAt | number | Execution deadline in Unix seconds when supplied. |
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 | Provider-specific ordered steps. Preserve their actual shapes and order; narrow the supported step format before invoking a wallet. |
meta | object | Provider execution metadata — providerQuoteId, deposit address, channel ID, wallet execution data. The serializer removes meta.raw, meta.params, and meta.route; other nested fields remain provider-specific. |
Only meta.raw, meta.params, and meta.route are explicitly removed by the
public execution serializer. Other provider fields remain opaque; this is not a
guarantee that all nested provider objects are sanitized for logging.
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. For uniswapx-order it is the UniswapX order. 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 | May describe wallet, signature, or deposit execution. Only meta.raw, meta.params, and meta.route are explicitly stripped. |
Errors
All failures use one envelope:
{
"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 |
| Selected route changed, or its deposit could not be tracked (execute, before any wallet action) | 409 | ROUTE_UNAVAILABLE |
| Transaction lookup not found | 404 | NOT_FOUND |
| Invalid capability or caller does not own transaction | 403 | FORBIDDEN |
| Tracking context/finalized reconciliation conflict | 409 | TRANSACTION_TRACKING_CONFLICT |
| Provider unavailable for the selected route | 409 / 503 | PROVIDER_UNAVAILABLE |
| Rate limited | 429 | RATE_LIMITED |
| Signature from a different wallet | 400 | INVALID_SIGNATURE |
| Order deadline passed before submission | 409 | ORDER_EXPIRED |
| Concurrent signature submission | 409 | SUBMISSION_IN_PROGRESS |
| 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:
Sign in
Connect your wallet and sign in to 7.Exchange.
Open the affiliate dashboard
Open the affiliate dashboard .
Create or copy a referral code
Your referral link contains the code.
Send it with the lock
Pass it as referralCode in POST /api/v1/quote/lock. Execute keeps the stored
code unless you send a different referralCode.
See the referral program for payout details.
Support
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.