API Reference

The 7.Exchange production API is ready for swap integrations.

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

All public swap integration endpoints are versioned under /api/v1. Use the endpoints below to discover assets and providers, request quotes, lock a selected route, execute the locked quote, and track resulting transactions. These swap integration endpoints do not require an API key unless an endpoint explicitly says otherwise.

Versioning Policy

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

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

Non-breaking changes can ship within the same version. Examples: adding a field, adding a new enum value, adding an optional request parameter, or adding metadata.

Breaking changes require a new path version. Examples: removing a field, renaming a field, changing a field type, changing required request fields, changing enum casing, or changing response envelope shape.

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

Response Conventions

• List endpoints return { "data": [ ... ], "pagination": { "page": 1, "perPage": 100, "total": 1, "hasMore": false } }.
• Quote preview returns { "data": [ ... ] } without pagination because it is a request-scoped route set, not a paginated resource.
• Single-resource and action endpoints return { "data": { ... } }.
• Error responses always return { "error": { ... } }.
• Rate-limited responses include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
• JSON request and response fields use camelCase.
• Amounts are strings unless a field is explicitly a count or basis-point number.
• Timestamps are ISO 8601 strings.
• Quote preview and lock responses return public route data and a fee object. They do not return execution payloads.
• Execute responses may include provider-specific quote, fee, exec, and providerResult objects. Use exec only for wallet execution; do not treat it as provider tracking state.
• Treat returned asset addresses as canonical for their chain. Compare EVM addresses case-insensitively unless you checksum them first.

Integration Flow

1. Fetch chains with GET /api/v1/swap/chains.
2. Fetch assets with GET /api/v1/swap/assets.
3. Fetch routing providers with GET /api/v1/swap/sources.
4. Request routes with POST /api/v1/quote.
5. Lock the selected provider route with POST /api/v1/quote/lock.
6. Execute the locked quote with POST /api/v1/quote/execute.
7. Poll transaction status with GET /api/v1/transaction/status.
8. If your client submits a wallet transaction or manual deposit after execute, send the public transaction.id and the resulting wallet/deposit hash to POST /api/v1/transaction/track.
9. Read transaction history with GET /api/v1/transaction/history.

If you are using the affiliate program, create an account in the 7.Exchange webapp, complete the affiliate flow, create or copy your referral link, and pass that link's code as referralCode in lock and execute requests.

Request Rules

• Send JSON request bodies with Content-Type: application/json.
• Use the chain key returned by GET /api/v1/swap/chains as srcChain and dstChain.
• Use the asset address returned by GET /api/v1/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 values are 0 through 10000 inclusive.
• Send the real source wallet as depositor and the real destination wallet as recipient when requesting and locking quotes.
• Do not hardcode provider names; use the provider returned by the selected quote.
• Use routeId from quote preview when locking a selected route.
• Use lockId from lock when executing.

Common Swap Schemas

Fee Object

fee is always an object on quote preview, lock, execute, and transaction responses. It may be empty when a provider does not expose fee details in a normalized form. Quote and execute responses usually use display-oriented fields; transaction status and history use recorded transaction fee fields.

Routes may also include feeBreakdown:

Transaction Asset Object

Transaction status and history responses include srcAsset and dstAsset snapshots. These are recorded when execute creates the transaction.

Execute exec Object

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

Common fields include:

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. They are documented with representative fields instead of blank placeholders. Integrators should read only the fields they need and tolerate additional provider fields.

Common provider-specific fields include:

Chains

GET /api/v1/swap/chains

Lists active supported chains.

Query Parameters

Example

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

Response

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

Assets

GET /api/v1/swap/assets

Lists supported swap assets. Use the returned address field in quote and lock requests.

Query Parameters

Example

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

Response

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

Sources

GET /api/v1/swap/sources

Lists active routing providers.

Query Parameters

Example

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

Response

{
  "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

Example

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"
  }'

Response

{
  "data": [
    {
      "provider": "ACROSS_PROTOCOL",
      "routeId": "provider-route-id",
      "src": {
        "formatted": "50",
        "currency": "USDC",
        "usd": "50"
      },
      "dst": {
        "formatted": "49.8",
        "currency": "USDC",
        "usd": "49.8"
      },
      "fee": {
        "usd": "0.20",
        "formatted": "0.20",
        "currency": "USD"
      },
      "feeBreakdown": {
        "total": {
          "usd": "0.20",
          "formatted": "0.20",
          "currency": "USD"
        },
        "items": [
          {
            "label": "Bridge fee",
            "type": "bridge",
            "amountUsd": 0.2,
            "currency": "USD"
          }
        ]
      },
      "estimatedTime": 120,
      "steps": [
        {
          "type": "bridge",
          "name": "Across",
          "image": "https://..."
        }
      ]
    }
  ]
}

Quote objects include provider-specific route fields, but they do not include execution payloads. Preserve the returned provider key and selected routeId until lock completes. If no route is available, this endpoint returns 200 with an empty data array.

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:

Example

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"
  }'

Response

The response includes the locked lockId needed by execute. It 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"
    },
    "fee": {
      "usd": "0.20",
      "formatted": "0.20",
      "currency": "USD"
    },
    "feeBreakdown": {
      "total": {
        "usd": "0.20",
        "formatted": "0.20",
        "currency": "USD"
      },
      "items": [
        {
          "label": "Bridge fee",
          "type": "bridge",
          "amountUsd": 0.2,
          "currency": "USD"
        }
      ]
    }
  }
}

Execute Quote

POST /api/v1/quote/execute

Executes the locked quote. Use the lockId returned by lock. The backend reads the locked source chain, destination chain, amount, slippage, provider, depositor, and recipient from the server-side lock record.

Body

Example

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

Response

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

{
  "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"
      },
      "steps": [
        {
          "type": "bridge",
          "name": "Across",
          "image": "https://..."
        }
      ]
    },
    "fee": {
      "usd": "0.20",
      "formatted": "0.20",
      "currency": "USD",
      "details": [
        {
          "label": "Bridge fee",
          "amountUsd": 0.2,
          "currency": "USD"
        }
      ]
    },
    "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 endpoint for polling after execute. The lookup accepts the public transaction id returned by execute, or any known transaction hash.

Query Parameters

Example

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

Response

{
  "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": [
          {
            "label": "Bridge fee",
            "amountUsd": 0.2,
            "currency": "USD"
          }
        ]
      },
      "srcAsset": {
        "id": 101,
        "symbol": "USDC",
        "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "image": "https://...",
        "chain": "ethereum"
      },
      "dstAsset": {
        "id": 202,
        "symbol": "USDC",
        "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "image": "https://...",
        "chain": "arbitrum"
      }
    },
    "final": false
  }
}

final is true when status is SUCCESS, FAILED, or REFUND. PENDING means polling should continue.

Track Transaction

POST /api/v1/transaction/track

Starts or refreshes provider status tracking for a transaction that was 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 transaction hash.
• The user manually sends a direct deposit and your client later learns the deposit transaction hash.
• You want to refresh backend-owned tracking for an already recorded transaction.

Do not send provider metadata such as provider key, request ID, channel ID, provider quote ID, chain ID, deposit address, or deposit memo. The backend stores provider tracking context during quote execution and ignores client-supplied provider metadata for tracking.

Body

Example

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

Response

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

After calling this endpoint, poll GET /api/v1/transaction/status with the same transactionId.

Tracking Guidance

For server-side provider execution, the backend usually records the provider reference and starts tracking during POST /api/v1/quote/execute. In that case, integrators should immediately poll GET /api/v1/transaction/status.

For client-side wallet execution:

1. Call POST /api/v1/quote/execute.
2. Read data.transaction.id.
3. Execute the wallet call described by data.exec, if one is present.
4. When the wallet returns an on-chain transaction hash, call POST /api/v1/transaction/track with { "transactionId": "...", "txHash": "..." }.
5. Poll GET /api/v1/transaction/status.

For signature-only flows, such as routes that 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.

For manual deposit flows:

1. Show the deposit instructions returned by execute.
2. Wait for the user or wallet provider to return the deposit transaction hash.
3. Call POST /api/v1/transaction/track with the public transactionId and deposit txHash.
4. Poll status.

Never ask users or integrators to provide provider request IDs, channel IDs, quote IDs, chain IDs, deposit addresses, or memos for tracking. Those values are backend-owned execution context.

Transaction History

GET /api/v1/transaction/history

Returns public transaction history. Pass wallet addresses to scope results to specific users or wallets.

Query Parameters

Example

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

Response

{
  "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": [
          {
            "label": "Bridge fee",
            "amountUsd": 0.2,
            "currency": "USD"
          }
        ]
      },
      "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
  }
}

Affiliate Referral Codes

There is no API-key generation flow for integrators.

To attribute swaps:

1. Create or sign in to a 7.Exchange account in the webapp.
2. Open the affiliate dashboard.
3. Create or copy a referral code.
4. Use the referral code as referralCode in POST /api/v1/quote/lock and POST /api/v1/quote/execute.

Common Failures

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"
        }
      ]
    }
  }
}

Clients should branch on error.code, not error.message. Messages are human-facing and may change. When multiple validation errors are found, they are returned in error.details.errors.

If no route is available during quote preview, POST /api/v1/quote returns 200 with:

{
  "data": []
}