Skip to Content
DevelopersAPI Reference

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.

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.

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 typeShips inExamples
Non-breakingSame versionAdding a field, adding an enum value, adding an optional request parameter, adding metadata
BreakingNew path versionRemoving 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 kindShape
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 from and to, exec.expiresAt, and X-RateLimit-Reset use Unix seconds; ttlMs uses milliseconds.
  • 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 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:

ScopeApplication limit
All /api/v1 requests100 per minute
History and platform statistics30 per minute
Transaction tracking5 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/chains

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

Query parameters

NameTypeDescription
pagenumberPage number. Defaults to 1.
perPagenumberResults per page. Defaults to 100, maximum 1000.
querystringSearch across name, shortname, and key.
typestringNetwork type filter: EVM, COSMOS, UTXO, or OTHER.
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

NameTypeDescription
pagenumberPage number. Defaults to 1.
perPagenumberResults per page. Defaults to 100, maximum 1000.
querystringSearch across name, symbol, and address.
chainstringChain key from GET /api/v1/swap/chains.
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

NameTypeDescription
pagenumberPage number. Defaults to 1.
perPagenumberDefaults to 100. Use 1–300; the source query caps results at 300 even if pagination echoes a larger requested value.
typestringProvider type: BRIDGE, EXCHANGE, or SERVICE.
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": 100, "total": 1, "hasMore": false } }

Integration Catalog

GET /api/v1/swap/integrations

Returns 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.

NameTypeDescription
pagenumberDefaults to 1.
perPagenumberDefaults to 100; use 1–200 for consistent paging. The catalog query caps results at 200.
querystringSearch display names and available keys/aliases.
typestringALL (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/quote

Returns available routes for the requested pair and amount.

Body

NameRequiredTypeDescription
srcChain✅stringSource chain key.
srcAddress✅stringSource asset address from the assets endpoint.
dstChain✅stringDestination chain key.
dstAddress✅stringDestination asset address from the assets endpoint.
amount✅stringPositive human-readable amount.
slippage—numberSlippage 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 | basicNEAR Intents execution mode. basic requests confidential handling; public is the default. Ignored by other providers.
depositor—stringSource wallet address. Recommended for accurate routes.
recipient—stringDestination wallet address. Recommended for accurate routes.
exclude—string[]Provider keys to exclude.
referrer—stringLegacy provider referrer context; separate from affiliate referralCode.
decimals—numberCompatibility input; source precision is resolved from backend asset metadata, not trusted from this value.
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" }'
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:

NameRequiredTypeDescription
provider✅stringProvider key from the selected quote.
depositor✅stringSource wallet address.
recipient✅stringDestination wallet address.
routeId—stringRoute ID from the selected quote. Recommended when multiple routes are returned.
referralCode—stringAffiliate referral code from your 7.Exchange referral link.
namespace—stringOptional 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 -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.

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 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/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. 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

NameRequiredTypeDescription
lockId✅stringLocked quote ID returned by POST /api/v1/quote/lock.
referralCode—stringAffiliate referral code. If omitted, the code stored on the lock is used.
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.

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" }, "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-signature

Submits 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.

NameRequiredTypeDescription
provider—stringDefaults to STARGATE.
providerQuoteId✅stringExecute-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.
Request body
{ "provider": "STARGATE", "providerQuoteId": "quote_provider_reference", "signatures": ["0x1234"] }
200 OK
{ "data": { "provider": "STARGATE", "providerQuoteId": "quote_provider_reference", "result": { "accepted": true } } }

UniswapX. Submit the swapper’s EIP-712 signature of providerResult.signTypedData before providerResult.deadline.

NameRequiredTypeDescription
provider✅stringUNISWAPX.
transactionId✅stringtransaction.id returned by execute.
trackingToken✅stringPrivate capability returned by execute. Never share or log it.
signature✅string65-byte (or 64-byte compact) hex signature by the swapper.
200 OK
{ "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/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

NameTypeDescription
transactionIdstringPublic transaction ID returned as transaction.id. Required when hash is omitted.
hashstringSearches hash, inboundHash, and outboundHash. Required when transactionId is omitted; a non-empty hash takes precedence if both are supplied. Prefer one lookup identifier.
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-one" } }, "final": false } }

Status values

StatusfinalMeaning
PENDINGfalseIn progress. Keep polling.
SUCCESStrueCompleted.
FAILEDtrueDid not complete.
REFUNDtrueFunds returned to the depositor.
EXPIREDtrueNo deposit was made before the swap’s deadline. No funds moved.

Track Transaction (deprecated)

POST /api/v1/transaction/track

Deprecated. 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

NameRequiredTypeDescription
transactionId✅stringPublic transaction ID returned as transaction.id.
txHash—stringDeprecated. Accepted for compatibility and ignored.
trackingToken—stringDeprecated. Accepted for compatibility and ignored.
curl -s "https://api.7.exchange/api/v1/transaction/track" \ -H "Content-Type: application/json" \ -d '{ "transactionId": "public-transaction-id" }'
200 OK
{ "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

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/history

Returns 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

NameTypeDescription
addressesstring | string[]Wallet address filter. Repeatable or comma-separated; at most 25 distinct addresses.
pagenumberPage number.
perPagenumberResults per page. Defaults to 20, maximum 50.
querystringSearch term.
referralCodestringExact referral code filter.
transactionIdstringPublic transaction ID filter.
statusesstring | string[]SUCCESS, PENDING, FAILED, REFUND, or EXPIRED. Repeatable or comma-separated.
finalizedOnlybooleanWhen true, only finalized records are returned: SUCCESS, FAILED, or REFUND by default, intersected with statuses if supplied (request EXPIRED explicitly).
from, tonumberOptional inclusive transaction creation-time bounds as non-negative Unix seconds. from must not exceed to.
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-one" } } ], "pagination": { "page": 1, "perPage": 20, "total": 1, "hasMore": false } }

Platform Statistics

GET /api/v1/transaction/stats

Returns public aggregate statistics for recorded SUCCESS transactions. The SDK does not currently wrap this endpoint.

NameTypeDescription
from, tonumberOptional 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"
200 OK
{ "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.

FieldTypeDescription
totalobjectNormalized total fee summary.
itemsarrayNormalized fee line items, each with a typed category and token identity when known.

fees.total:

FieldTypeDescription
usdstringEstimated total fee value in USD.
formattedstringHuman-readable total fee value.

fees.items[]:

FieldTypeDescription
typestringOne of the fee item types.
amountstringBase-unit token amount for this item. Use token.decimals for display. May be signed for rewards or rebates.
tokenobjectToken identity: chainId, address, symbol, decimals.
amountUsdstringEstimated USD value when known.
descriptionstringHuman-readable explanation from the backend or provider.
providerLabelstringOriginal provider label, useful for debugging or display.
chainobjectChain identity: chainId, sometimes name.

Fee item types

TypeDescription
source_gasSource-chain gas or network cost.
destination_gasDestination-chain gas, outbound, or egress cost.
liquidity_feeLiquidity provider, pool, or route liquidity fee.
protocol_feeProvider or protocol service fee not more specifically classified.
bridge_feeBridge or relayer service fee for cross-chain transfer execution.
integrator_feeAffiliate, broker, or integrator fee.
swap_impactPrice impact, spread, or market-depth value impact from a swap leg.
route_lossQuote-level route value loss not exposed by the provider as a specific fee item.
messaging_feeCross-chain message delivery fee, such as a LayerZero messaging fee.
boost_feeOptional speed, priority, or boost fee.
gas_drop_feeDestination native-token gas drop sent to the recipient.
cctp_feeCircle CCTP receive, attestation, or finality fee.
transfer_feeToken or network transfer fee not captured by gas, bridge, or protocol categories.
transfer_rewardReward, rebate, or negative fee that offsets route cost.
otherProvider 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.

FieldTypeDescription
amountstring | nullRecorded fee amount when known.
amountUsdnumber | nullRecorded fee value in USD when known.
currencystring | nullCurrency or token symbol for amount.
detailsobject | array | nullRecorded 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.

FieldTypeDescription
idnumber | nullInternal asset ID.
symbolstring | nullToken symbol.
contractstring | nullToken contract address, or null for native assets.
imagestring | nullToken image URL.
chainstring | nullChain 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.

FieldTypeDescription
chainIdnumber | nullNumeric source chain ID for wallet execution when applicable.
providerTargetstringContract, deposit, or provider target address for a wallet call.
providerCalldatastringHex calldata for EVM wallet execution.
valuestringNative token value to send, in base units.
expiresAtnumberExecution deadline in Unix seconds when supplied.
srcTokenstringSource token address or native.
srcAmountstringSource amount in base units.
approvalTargetstringToken approval spender when an approval is required.
approvalTokenstringToken to approve when an approval is required.
approvalAmountstringApproval amount in base units.
allStepsarrayProvider-specific ordered steps. Preserve their actual shapes and order; narrow the supported step format before invoking a wallet.
metaobjectProvider 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.

ObjectCommon fieldsNotes
providerResulttxHash, status, requestId, channelId, depositAddress, depositMemo, executionShape depends on provider and execution mode. For uniswapx-order it is the UniswapX order. Never send these back to tracking.
quotesrc, dst, steps, fees, estimatedTimeStored route snapshot used for display and transaction recording.
exec.metaproviderQuoteId, selectedQuoteId, executionMode, walletExecution, depositAddress, channelIdMay describe wallet, signature, or deposit execution. Only meta.raw, meta.params, and meta.route are explicitly stripped.

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.

FailureStatusCode
Missing or invalid required field400VALIDATION_ERROR
Invalid amount400INVALID_AMOUNT
Invalid slippage400INVALID_SLIPPAGE
Invalid participant address400INVALID_ADDRESS
Same-chain same-asset swap400UNSUPPORTED_PAIR
Missing provider on lock400MISSING_PROVIDER
Missing lockId on execute400MISSING_LOCK_ID
Expired or already-used lock409QUOTE_EXPIRED
Selected route changed, or its deposit could not be tracked (execute, before any wallet action)409ROUTE_UNAVAILABLE
Transaction lookup not found404NOT_FOUND
Invalid capability or caller does not own transaction403FORBIDDEN
Tracking context/finalized reconciliation conflict409TRANSACTION_TRACKING_CONFLICT
Provider unavailable for the selected route409 / 503PROVIDER_UNAVAILABLE
Rate limited429RATE_LIMITED
Signature from a different wallet400INVALID_SIGNATURE
Order deadline passed before submission409ORDER_EXPIRED
Concurrent signature submission409SUBMISSION_IN_PROGRESS
Backend error500INTERNAL_ERROR
Upstream / provider error502 / 503BAD_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.

Last updated on