10FI Partner API Quickstart

Base URL: https://api.10fi.org

10FI is B2B API-first. Your app/wallet/exchange keeps the user relationship; 10FI returns neutral quote and execution payloads.

---

Start here

New to 10FI? Follow these steps in order.

1. Get credentials

Email [email protected] with your company name and which products you need. You receive:

| Credential | Prefix | Purpose |

|------------|--------|---------|

| X-Client-Id | ci_ | Identifies your merchant account |

| X-API-Key | sk_ | Authenticates every request (keep secret) |

One key can access multiple products. No separate key per product.

2. Check health

curl "https://api.10fi.org/v1/health"

Expected: {"status":"ok"}. No auth required.

3. Request a quote (BSC same-chain)

curl "https://api.10fi.org/v1/quote?chain=bsc&from=USDT&to=WBNB&amount=100&routePreference=best-value" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Requires: swap_api entitlement.

4. Build a swap

curl -X POST "https://api.10fi.org/v1/swap" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{"chain":"bsc","from":"USDT","to":"WBNB","amount":"100","userAddress":"0xYourWallet","slippageBps":50}'

Your wallet sends the returned tx object. User pays network gas.

5. Poll cross-chain status (if using cross-chain)

curl "https://api.10fi.org/v1/transfer-status?txHash=0xYourTxHash&fromChain=tron&toChain=bsc" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Requires: cross_chain_api entitlement.

6. Understand errors

Every error returns:

{"code":"ERROR_CODE","message":"Human-readable explanation","requestId":"a1b2c3d4"}

See the full Error Catalog for all codes, retry guidance, and merchant actions.

Which API product do I need?

One 10FI API key can access one or more products. Tell support which products you need — you do not need separate keys.

|---------------|---------|------------------|------------|

| Same-chain token swap (e.g., USDT → BNB on BSC) | Swap API | swap_api | User pays network gas on standard routes. Swap API is not always gasless — set preferGasless: false unless you specifically want gasless. |

| Sponsored gas / zero-gas transaction for user | Gasless API | gasless_api | Currently pilot/mock only unless 10FI explicitly enables production gasless for your account. Do not build your UX around gasless being available. |

> One key, multiple entitlements. A single X-Client-Id / X-API-Key pair can have swap_api + cross_chain_api + gasless_api enabled simultaneously. You never need to request a second key for a different product.

What is not live yet?

Gasless real sponsorship is not live unless gasless_api is explicitly enabled for your account by 10FI. Mock responses are returned by default. Do not assume gasless is available.
Own-router execution is not enabled. All routing uses external liquidity providers.
All examples use placeholder credentials and mock data. No real funds are involved.

Next steps

Full API reference: Soft Launch API Guide (below)
Copy-paste curl examples: pilot-merchant examples
Error codes and retry guidance: Error Catalog
Admin onboarding: Merchant Admin Runbook

---

First successful request checklist

Run these in order. If any step fails, see Troubleshooting below.

|---|---------|----------|-------------|

| 1 | GET /v1/health | {"status":"ok"} | None |

| 6 | Trigger a 403 error intentionally | {"code":"FORBIDDEN",...} | Verify error shape works |

If all 6 pass, your integration is ready for pilot testing.

---

Merchant-safe troubleshooting

| You see | Cause | Fix |

|---------|-------|-----|

| 401 UNAUTHORIZED — "API credentials required" | Missing X-Client-Id or X-API-Key header | Add both headers to every request. Check for typos in ci_ / sk_ prefixes. |

| 401 UNAUTHORIZED — "Invalid credentials" | X-Client-Id and X-API-Key do not match, or key is revoked | Verify both values in your merchant dashboard. Generate a new key if needed. |

| 403 FORBIDDEN — "This product is not enabled" | Your key does not have the required product entitlement | Contact 10FI to enable the product (swap_api, gasless_api, or cross_chain_api) on your key. |

| 429 RATE_LIMITED | Per-key or per-IP rate limit exceeded | Wait for retryAfterSec seconds (check the response body and Retry-After header). Upgrade tier for higher limits. |

| QUOTE_UNAVAILABLE — "No routes available" | No liquidity route exists for your token pair/amount/chain | Try a different token pair, adjust the amount, or switch chains. |

| UPSTREAM_ERROR (502) | Provider timed out or returned an error | Retry after 2-5 seconds. If persistent for >1 minute, contact support with the requestId. |

| INVALID_REQUEST (400) — "Missing required parameter" | Required field absent (chain, from, to, amount, userAddress) | Check the message field — it names the missing parameter. |

| INVALID_REQUEST (400) — "Unsupported chain" | Chain name not recognized | Use: bsc, ethereum, polygon, base, arbitrum, optimism, tron, solana. |

| Cross-chain status stuck on PENDING | Bridge is still processing | Poll every 30 seconds. If stuck for >5 minutes, contact support with the requestId. |

> What to send to 10FI support when you hit an error:

> 1. The requestId from the error response (e.g., "a1b2c3d4")

> 2. The full error JSON (code, message, requestId)

> 3. Your X-Client-Id (the ci_ value, NOT the sk_ key)

> 4. A description of what you were trying to do

> Never send your X-API-Key (sk_) to support.

---

Products

|---------|----------|---------------|------------------------|

Do not claim every Swap API route is gasless. Docs: Swap API · Gasless API

Auth

Send both headers on every API call:

X-Client-Id: ci_your_client_id
X-API-Key: sk_your_api_key

One merchant key can use Swap API, Gasless API, and Cross-chain API if those products are enabled for that merchant. There is no need to request a separate key per product — enablement is a per-account setting on your existing client_id/api_key pair. A call to a product that isn't enabled for your account returns a 403 FORBIDDEN response; contact 10FI to have a product enabled.

Sandbox

Sandbox endpoints are deterministic, signed, and never touch liquidity providers or real funds.

curl "https://api.10fi.org/v1/sandbox/quote?chain=bsc&from=USDT&to=BNB&amount=100&routePreference=fastest" \
  -H "X-Client-Id: $TENFI_CLIENT_ID" \
  -H "X-API-Key: $TENFI_API_KEY"

curl -X POST "https://api.10fi.org/v1/sandbox/swap" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: $TENFI_CLIENT_ID" \
  -H "X-API-Key: $TENFI_API_KEY" \
  -d '{"chain":"bsc","from":"USDT","to":"BNB","amount":"100","routePreference":"fastest"}'

Never broadcast sandbox transactions. They are dummy integration payloads only.

Live quote

curl "https://api.10fi.org/v1/quote?chain=bsc&from=USDT&to=BNB&amount=100&routePreference=best-value" \
  -H "X-Client-Id: $TENFI_CLIENT_ID" \
  -H "X-API-Key: $TENFI_API_KEY"

Supported routePreference values:

best-value
fastest
balanced

The response exposes neutral fields only:

best / selected
cheapest
fastest
balanced
routing

Live swap build

curl -X POST "https://api.10fi.org/v1/swap" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: $TENFI_CLIENT_ID" \
  -H "X-API-Key: $TENFI_API_KEY" \
  -d '{
    "chain":"bsc",
    "from":"USDT",
    "to":"BNB",
    "amount":"100",
    "userAddress":"0xYourWallet",
    "preferGasless":true,
    "routePreference":"best-value",
    "slippageBps":50
  }'

If steps[] is present, send each transaction in order. Otherwise send tx.

Transfer status

curl "https://api.10fi.org/v1/transfer-status?txHash=0x...&fromChain=polygon&toChain=base" \
  -H "X-Client-Id: $TENFI_CLIENT_ID" \
  -H "X-API-Key: $TENFI_API_KEY"

Webhooks

Configure a callback URL from the merchant dashboard API:

curl -X POST "https://api.10fi.org/v1/merchant/webhook" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TENFI_MERCHANT_SESSION" \
  -d '{"url":"https://partner.example/webhooks/10fi","enabled":true,"rotateSecret":true}'

Save the returned secret; it is shown once.

10FI signs webhook bodies with:

X-10FI-Webhook-Timestamp: <unix seconds>
X-10FI-Webhook-Signature: t=<unix seconds>,v1=<hmac_sha256>

Signature payload:

<timestamp>.<raw JSON body>

HMAC key: your webhook secret.

Send a test event:

curl -X POST "https://api.10fi.org/v1/merchant/webhook/test" \
  -H "Authorization: Bearer $TENFI_MERCHANT_SESSION"

---

Soft Launch API Guide

This section provides step-by-step integration examples for pilot merchants. All request/response bodies use placeholder credentials and deterministic mock data. No real funds or liquidity providers are involved in these examples.

Authentication

Every API call requires two headers:

X-Client-Id: ci_your_client_id
X-API-Key: sk_your_api_key

Client ID (ci_ prefix): identifies your merchant account.
API Key (sk_ prefix): authenticates the request. Keep this secret; never commit it to source control.

One merchant API key can be entitled to multiple products:

| Product entitlement | Grants access to |

|---------------------|------------------|

| swap_api | Same-chain quote and swap (/v1/quote, /v1/swap with chain only) |

| gasless_api | Sponsored gas routes (/v1/gasless/*, /v1/submit, /v1/status/:orderId) |

| cross_chain_api | Bridge/cross-chain swaps (/v1/quote//v1/swap with toChain, /v1/transfer-status) |

If your API key calls a product that is not enabled for your account, the API returns:

{
  "code": "FORBIDDEN",
  "message": "Product not enabled for this account. Contact 10FI to enable: cross_chain_api",
  "error": "Product not enabled for this account. Contact 10FI to enable: cross_chain_api",
  "requestId": "req_abc123",
  "reqId": "req_abc123"
}

code is the machine-readable field to branch on. error/reqId are deprecated aliases of message/requestId kept for backward compatibility — never rely on error holding the machine code.

Contact 10FI support to enable additional products on your key.

---

BSC Same-Chain Swap — Quote

Request a real-time quote for swapping USDT → BNB on BSC:

curl "https://api.10fi.org/v1/quote?chain=bsc&from=USDT&to=WBNB&amount=100000000000000000000&routePreference=best-value" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Placeholder response:

{
  "requestId": "req_demo_quote_bsc_001",
  "chain": "bsc",
  "from": "USDT",
  "to": "WBNB",
  "amount": "100000000000000000000",
  "best": {
    "source": "10fi-onchain",
    "amountIn": "100000000000000000000",
    "amountOut": "294117647058823529",
    "netValueUSD": 198.50
  },
  "cheapest": {
    "source": "10fi-onchain",
    "amountIn": "100000000000000000000",
    "amountOut": "293500000000000000",
    "netValueUSD": 198.10
  },
  "fastest": {
    "source": "10fi-onchain",
    "amountIn": "100000000000000000000",
    "amountOut": "292000000000000000",
    "netValueUSD": 197.30
  },
  "routesConsidered": 3
}

> Note: All response fields are sanitized. Internal source names, routing details, and fee breakdowns are stripped before reaching your server.

---

BSC Same-Chain Swap — Build Transaction

Once you have a quote, build the swap transaction:

curl -X POST "https://api.10fi.org/v1/swap" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{
    "chain": "bsc",
    "from": "USDT",
    "to": "WBNB",
    "amount": "100000000000000000000",
    "userAddress": "0xYourWalletAddress",
    "routePreference": "best-value",
    "slippageBps": 50
  }'

Placeholder response:

{
  "requestId": "req_demo_swap_bsc_001",
  "type": "onchain",
  "tx": {
    "to": "0xTargetContractFromApiResponse",
    "data": "0x38ed1739000000...00000000000000000000000000000000000000000000000000000000",
    "value": "0",
    "gasLimit": "350000",
    "gasPrice": "3000000000"
  },
  "quote": {
    "amountIn": "100000000000000000000",
    "amountOut": "294117647058823529"
  }
}

Your wallet sends this transaction. The user pays the network gas fee.

---

Cross-Chain: TRON USDT → BSC USDT

Cross-chain quotes use the same /v1/quote endpoint with a toChain parameter. This requires the cross_chain_api product entitlement.

Step 1: Get a cross-chain quote

curl "https://api.10fi.org/v1/quote?chain=tron&toChain=bsc&from=USDT&to=USDT&amount=100000000&routePreference=best-value" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Placeholder response:

{
  "requestId": "req_demo_xchain_quote_001",
  "chain": "tron",
  "toChain": "bsc",
  "from": "USDT",
  "to": "USDT",
  "amount": "100000000",
  "best": {
    "source": "10fi-crosschain",
    "amountIn": "100000000",
    "amountOut": "99950000",
    "netValueUSD": 99.95
  },
  "routesConsidered": 2
}

Step 2: Build the cross-chain swap

curl -X POST "https://api.10fi.org/v1/swap" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{
    "chain": "tron",
    "toChain": "bsc",
    "from": "USDT",
    "to": "USDT",
    "amount": "100000000",
    "userAddress": "TYourTronWalletAddress",
    "routePreference": "best-value",
    "slippageBps": 100
  }'

Placeholder response:

{
  "requestId": "req_demo_xchain_swap_001",
  "type": "onchain",
  "tx": {
    "to": "TTargetContractFromApiResponse",
    "data": "41a9059cbb0000000000000000000000...",
    "value": "0"
  },
  "quote": {
    "amountIn": "100000000",
    "amountOut": "99950000"
  }
}

Step 3: Track the cross-chain transfer

After submitting the source-chain transaction, track the bridge status:

curl "https://api.10fi.org/v1/transfer-status?txHash=0xYourSourceTxHash&fromChain=tron&toChain=bsc" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Placeholder response:

{
  "status": "COMPLETED",
  "fromChain": "tron",
  "toChain": "bsc",
  "sourceTxHash": "0xYourSourceTxHash",
  "destTxHash": "0xYourDestTxHash",
  "amountIn": "100000000",
  "amountOut": "99950000"
}

---

Cross-Chain: BSC → Solana

Same pattern, different chain pair. Requires cross_chain_api entitlement.

Quote:

curl "https://api.10fi.org/v1/quote?chain=bsc&toChain=solana&from=USDC&to=USDC&amount=100000000&routePreference=fastest" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Placeholder response:

{
  "requestId": "req_demo_xchain_sol_001",
  "chain": "bsc",
  "toChain": "solana",
  "from": "USDC",
  "to": "USDC",
  "amount": "100000000",
  "best": {
    "source": "10fi-crosschain",
    "amountIn": "100000000",
    "amountOut": "99920000",
    "netValueUSD": 99.92
  },
  "routesConsidered": 2
}

Swap:

curl -X POST "https://api.10fi.org/v1/swap" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{
    "chain": "bsc",
    "toChain": "solana",
    "from": "USDC",
    "to": "USDC",
    "amount": "100000000",
    "userAddress": "0xYourBscWalletAddress",
    "routePreference": "fastest",
    "slippageBps": 100
  }'

Placeholder response:

{
  "requestId": "req_demo_xchain_sol_swap_001",
  "type": "onchain",
  "tx": {
    "to": "0xTargetContractFromApiResponse",
    "data": "0x...",
    "value": "0",
    "gasLimit": "400000"
  },
  "quote": {
    "amountIn": "100000000",
    "amountOut": "99920000"
  }
}

Track with /v1/transfer-status using the source transaction hash, fromChain=bsc, toChain=solana.

---

Gasless Flow (Shadow/Mock — Not Enabled for Production)

> Important: The Gasless API is a separate product. The examples below are shadow/mock only and will not execute real transactions unless gasless_api is explicitly enabled for your account by 10FI. Currently, no pilot merchants have production gasless enabled.

Gasless API lets you submit swaps where the gas fee is sponsored (the user pays zero network gas on supported routes).

Step 1: Get a gasless quote

curl "https://api.10fi.org/v1/gasless/quote?chain=bsc&from=USDT&to=WBNB&amount=100000000000000000000" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Placeholder response:

{
  "requestId": "req_demo_gasless_quote_001",
  "type": "gasless",
  "chain": "bsc",
  "from": "USDT",
  "to": "WBNB",
  "amount": "100000000000000000000",
  "quote": {
    "amountIn": "100000000000000000000",
    "amountOut": "294000000000000000"
  },
  "gasEstimateUSD": 0.12,
  "_status": "shadow-mock"
}

Step 2: Prepare the gasless transaction

curl -X POST "https://api.10fi.org/v1/gasless/prepare" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{
    "chain": "bsc",
    "from": "USDT",
    "to": "WBNB",
    "amount": "100000000000000000000",
    "userAddress": "0xYourWalletAddress"
  }'

Placeholder response:

{
  "requestId": "req_demo_gasless_prep_001",
  "type": "gasless",
  "toSign": {
    "domain": { "name": "10FI Settlement", "chainId": 56 },
    "types": { "Swap": [{ "name": "amountIn", "type": "uint256" }] },
    "value": { "amountIn": "100000000000000000000" }
  },
  "_status": "shadow-mock"
}

Step 3: Sign and submit

After signing toSign with the user's wallet, submit the signed payload:

curl -X POST "https://api.10fi.org/v1/gasless/submit" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{
    "chain": "bsc",
    "signature": "0xSignedByUserWallet...",
    "toSign": { "domain": {}, "types": {}, "value": {} }
  }'

Placeholder response:

{
  "requestId": "req_demo_gasless_sub_001",
  "orderId": "order_demo_abc123",
  "status": "PENDING",
  "_status": "shadow-mock"
}

Step 4: Check status

curl "https://api.10fi.org/v1/gasless/status/order_demo_abc123" \
  -H "X-Client-Id: ci_your_client_id" \
  -H "X-API-Key: sk_your_api_key"

Placeholder response:

{
  "orderId": "order_demo_abc123",
  "status": "COMPLETED",
  "txHash": "0xGaslessSettlementTxHash",
  "_status": "shadow-mock"
}

---

Merchant Onboarding Checklist

Before integrating, provide 10FI with the following:

| Item | Example | Required |

|------|---------|----------|

| Company name | Acme Wallet Inc. | Yes |

| Contact email | [email protected] | Yes |

| Enabled products | swap_api, cross_chain_api (or all three) | Yes |

| Rate limit tier | Free / Pro / Enterprise | Yes |

| Webhook URL | https://acme-wallet.example/webhooks/10fi | No — only if you need order status push notifications |

| Test wallet address (BSC) | 0xTestBscWallet000000000000000000000000000 | Yes |

| Test wallet address (TRON) | TTestTronWallet00000000000000000000000000 | If using cross-chain |

Once 10FI provisions your account, you receive:

X-Client-Id (ci_ prefix)
X-API-Key (sk_ prefix)
Enabled product list

Test against the sandbox endpoints first (/v1/sandbox/*) — they return deterministic responses with no real fund movement.

Developer docs
Developer Docs Partner Quickstart Swap API Gasless API Error Catalog Pilot Examples Cross-chain Guides Comparisons