> For the complete documentation index, see [llms.txt](https://docs-swap.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-swap.crypto-chief.com/getting-started/readme.md). # General Information The **Swap API** finds the best route across DEXs for a token swap and returns unsigned transactions that your wallet signs and sends. It never holds funds and never signs anything. The route is chosen by its net result: the expected output minus the network cost of every step, converted into the output token, minus a risk penalty. Every quote shows that arithmetic: output, guaranteed minimum, network fees, pool fees, route and risk. ## Base URL ``` https://swap-api.crypto-chief.com/YOUR_API_KEY/v1/ ``` ## Authentication `YOUR_API_KEY` is your project UUID: the **Merchant ID** in the Dashboard under **Project Settings → Integration**, the same key your RPC Gateway URLs use. It goes in the path; there is no signature and no authorization header. Keep it server-side: anyone with the full URL spends your credits. See [Authentication](/getting-started/authentication.md). ## How a swap runs 1. [**Quote**](/api-reference/quote.md) — `POST /v1/quote` prices the swap: output, fees, route, risk. Without `from_address` it is a pure estimate with no wallet checks. 2. [**Build**](/api-reference/build.md) — `POST /v1/build` with `from_address` returns `steps[]`: one unsigned `transaction` per step, in the network's own format. 3. **Sign and send each step in order** with your own wallet or key. When a step has `wait_for_confirmation: true`, wait for it to confirm before signing the next one. 4. **Rebuild when a step says so.** A step with `rebuild_after_previous: true` means: call `/v1/build` again with the same parameters after the previous step confirms, and continue with the steps of the new response. [How a Swap Works](/getting-started/how-a-swap-works.md) explains all of this in detail; [Signing on Each Network](/guides/signing.md) shows the code. ## Networks Network codes are case-insensitive. [`POST /v1/networks`](/api-reference/networks.md) returns this list with live readiness. | Family | Mainnets | Testnets | | ---------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | EVM | `ETH_MAINNET`, `BSC_MAINNET`, `POLYGON_MAINNET`, `ARBITRUM_ONE`, `OPTIMISM_MAINNET`, `AVAX_MAINNET` | `ETH_SEPOLIA`, `BSC_TESTNET`, `ARBITRUM_SEPOLIA`, `OPTIMISM_SEPOLIA`, `AVAX_TESTNET` | | TRON | `TRON_MAINNET` | `TRON_NILE` | | Solana | `SOLANA_MAINNET` | — | | TON | `TON_MAINNET` | — | | XRP Ledger | `XRP_MAINNET` | `XRP_TESTNET` | ## The endpoints All operations are `POST` with a JSON object body to `https://swap-api.crypto-chief.com/YOUR_API_KEY/v1/`. | Method | Path | What it does | | ------ | ------------------------------------------------------------------ | -------------------------------------------------------- | | `POST` | [`/v1/quote`](/api-reference/quote.md) | Price a swap: output, fees, route, risk | | `POST` | [`/v1/build`](/api-reference/build.md) | Fresh quote plus the unsigned transactions to execute it | | `POST` | [`/v1/approve/spender`](/api-reference/approve-spender.md) | The address a token approval must go to (EVM, TRON) | | `POST` | [`/v1/approve/allowance`](/api-reference/approve-allowance.md) | The current allowance of a wallet (EVM, TRON) | | `POST` | [`/v1/approve/transaction`](/api-reference/approve-transaction.md) | Build an unsigned approval transaction (EVM, TRON) | | `POST` | [`/v1/networks`](/api-reference/networks.md) | Enabled networks and their live readiness | | `POST` | [`/v1/tokens`](/api-reference/tokens.md) | The tokens of a network | | `POST` | [`/v1/liquidity-sources`](/api-reference/liquidity-sources.md) | The liquidity sources and executors of a network | Any other path answers `404 NOT_FOUND`; any other method answers `405 METHOD_NOT_ALLOWED`. ## Billing Calls are charged to your **platform API credits** — the same balance the RPC Gateway spends. A quote costs 1,000 credits ($0.0001), a build 10,000 ($0.001), and approvals and reference data 260 each ($0.000026). Availability failures your request cannot cause are refunded. The full price list and the exact refund rule are in [Billing](/getting-started/billing.md). ## Your first request Quote 1,000 USDC swapped to ETH on Ethereum. No `from_address`, so no wallet is checked — this is a pure estimate. `swap()` is defined in [Authentication](/getting-started/authentication.md). {% tabs %} {% tab title="JavaScript" %} ```javascript const quote = await swap("quote", { network: "ETH_MAINNET", token_in: "USDC", token_out: "NATIVE", amount_in: "1000000000", // 1000 USDC in base units (6 decimals) }); console.log(quote); ``` {% endtab %} {% tab title="PHP" %} ```php $quote = swap('quote', [ 'network' => 'ETH_MAINNET', 'token_in' => 'USDC', 'token_out' => 'NATIVE', 'amount_in' => '1000000000', // 1000 USDC in base units (6 decimals) ]); print_r($quote); ``` {% endtab %} {% tab title="GO" %} ```go quote, status, err := swap("quote", map[string]any{ "network": "ETH_MAINNET", "token_in": "USDC", "token_out": "NATIVE", "amount_in": "1000000000", // 1000 USDC in base units (6 decimals) }) if err != nil { log.Fatal(err) } fmt.Println(status, quote) ``` {% endtab %} {% tab title="Python" %} ```python quote = swap("quote", { "network": "ETH_MAINNET", "token_in": "USDC", "token_out": "NATIVE", "amount_in": "1000000000", # 1000 USDC in base units (6 decimals) }) print(quote) ``` {% endtab %} {% tab title="curl" %} ```bash curl -s -X POST "https://swap-api.crypto-chief.com/$CC_API_KEY/v1/quote" \ -H "Content-Type: application/json" \ -d '{"network":"ETH_MAINNET","token_in":"USDC","token_out":"NATIVE","amount_in":"1000000000"}' ``` {% endtab %} {% endtabs %} ```json { "quote_id": "0b6f8c7e-6a43-4d0a-9d7e-3c2f5a1e9b10", "network": "ETH_MAINNET", "family": "EVM", "token_in": {"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "decimals": 6, "kind": "token", "flags": ["pausable", "blacklist"]}, "token_out": {"address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "symbol": "ETH", "decimals": 18, "kind": "native"}, "amount_in": "1000000000", "amount_in_human": "1000", "amount_out": "263157894736842105", "amount_out_human": "0.263157894736842105", "amount_out_min": "261842105263157894", "amount_out_min_human": "0.261842105263157894", "slippage_bps": 50, "net_amount_out": "261961578947368421", "price_impact_bps": 4, "fees": { "network": { "native_symbol": "ETH", "cost_native": "1170000000000000", "cost_native_human": "0.00117", "cost_in_token_out": "1170000000000000", "cost_usd": "4.45", "gas_limit": 180000, "unit_price": "12000000000", "effective_unit_price": "6500000000" }, "pools": [ {"source": "uniswap_v3", "pool": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640", "fee_bps": 5.0, "fee_amount": "300000", "fee_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}, {"source": "sushi_v2", "pool": "0x397FF1542f962076d0BFE58eA045FfA2d347ACa0", "fee_bps": 30.0, "fee_amount": "1200000", "fee_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"} ], "service": {"bps": 0, "amount": "0"} }, "route": { "splits": [ { "share_bps": 6000, "amount_in": "600000000", "amount_out": "157894736842105263", "hops": [ {"source": "uniswap_v3", "pool": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640", "kind": "uni_v3", "token_in": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "token_out": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "fee_bps": 5.0, "amount_in": "600000000", "amount_out": "157894736842105263"} ] }, { "share_bps": 4000, "amount_in": "400000000", "amount_out": "105263157894736842", "hops": [ {"source": "sushi_v2", "pool": "0x397FF1542f962076d0BFE58eA045FfA2d347ACa0", "kind": "uni_v2", "token_in": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "token_out": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "fee_bps": 30.0, "amount_in": "400000000", "amount_out": "105263157894736842"} ] } ] }, "executor": {"id": "sushi_rp5", "address": "0xf2614A233c7C3e7f08b1F887Ba133a13f1eb2c55", "atomic": true, "third_party": true, "onchain_deadline": false, "transactions": 1}, "risk": { "level": "low", "score": 12, "penalty": "26315789473684", "factors": [ {"code": "third_party_router", "level": "low", "message": "executor contract is controlled by a third party", "cost": "26315789473684"} ] }, "setup_required": false, "state": {"reference": 23651200, "age_ms": 1800}, "expires_at": "2026-10-25T12:00:30Z", "search": {"engine": "native", "paths_considered": 18, "pools_considered": 42, "elapsed_ms": 21, "truncated": false}, "warnings": ["from_address is not set: allowances are not checked and approvals are not included"] } ``` Amounts are decimal strings in **base units** (wei, sun, lamports, nanoTON, drops); the `*_human` fields carry the same amounts with decimals applied. `amount_out_min` is the guaranteed minimum: below it, the swap transaction does not execute. {% hint style="info" %} Without `from_address` no wallet is read: allowances are not checked and the estimate cannot know an approval is missing (`setup_required` stays `false`, and `warnings` says so). Pass `from_address` and the quote reflects your wallet; [`POST /v1/build`](/api-reference/build.md) then returns any setup steps as unsigned transactions ahead of the swap step. {% endhint %} ## Before you build Read these two pages before building: * [How a Swap Works](/getting-started/how-a-swap-works.md) — quote vs build, the order of steps, rebuilds, deadlines, and what can still fail on chain. * [Networks and Tokens](/getting-started/networks-and-tokens.md) — network codes, how to name a token, and base units.