Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Quickstart: your first swap

Go from zero to a tracked cross-chain swap: get an API key, request a quote, build the transaction, sign it, and track it to completion.

This walks through one complete swap, selling ETH on Ethereum for BTC, using plain HTTP. Every SwapKit swap follows the same four calls: quote → swap → sign and broadcast → track. Once this works, every other pair and chain is a change of parameters.

SwapKit is non-custodial: the API builds transactions, but your user signs and broadcasts them with their own wallet. SwapKit never holds keys or funds.

1. Get an API key

  1. Sign in to the SwapKit dashboard.

  2. Click Create app.

  3. Open the app and copy its API Key.

Send it in the x-api-key header on every request. A new key allows 10 requests per minute on each service and trades of up to $1,000; both can be raised. See Authentication and API keys.

export SWAPKIT_API_KEY="YOUR_API_KEY"

2. Request a quote

/v3/quote prices the swap across every provider. No addresses are needed yet.

curl -X POST "https://api.swapkit.dev/v3/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SWAPKIT_API_KEY" \
  -d '{
    "sellAsset": "ETH.ETH",
    "buyAsset": "BTC.BTC",
    "sellAmount": "0.05",
    "slippage": 3
  }'

Assets are identified as CHAIN.TICKER, or CHAIN.TICKER-contractAddress for tokens, for example ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48. Look identifiers up with /tokens. sellAmount is in whole units, so "0.05" is 0.05 ETH.

The response holds one entry in routes per provider that can fill the trade. The fields you need first:

Field
Use

routes[].routeId

Identifies the route. You pass it to /v3/swap.

routes[].expectedBuyAmount

What the user should receive, to show them before they commit.

routes[].meta.tags

RECOMMENDED, FASTEST or CHEAPEST, to help pick a route.

routes[].providers

Which provider or providers execute the route.

To list routes side by side:

A quote is valid for 5 minutes.

3. Build the transaction

When the user accepts a route, call /v3/swap with its routeId and the user's addresses: sourceAddress on the sell chain (Ethereum) and destinationAddress on the buy chain (Bitcoin).

SwapKit checks that sourceAddress holds enough to cover sellAmount, screens both addresses, and returns the route with a ready-to-sign transaction:

  • tx is the transaction to sign. Its format depends on the sell chain.

  • meta.txType names that format, here EVM.

  • targetAddress is where the funds go: a deposit address or a contract.

Use an address you control with real funds. An unfunded sourceAddress returns insufficientBalance.

4. Sign and broadcast

Sign tx with the user's wallet and broadcast it like any other transaction on that chain. For an EVM route, tx carries to, from, data, value, gas and gasPrice as hex strings. With viem:

Each chain returns its own format, such as a PSBT for Bitcoin or a serialized transaction for Solana. Transaction Formats by txType shows an example response for each one.

5. Track the swap

Pass the transaction hash and the sell chain's ID to /track. Ethereum is "1"; the other chain IDs are in the /providers page.

Poll status until it reads completed, refunded or failed. Users can follow the same swap at https://track.swapkit.dev/?hash=0xYOUR_TRANSACTION_HASH.

Next steps

Last updated