Quickstart

This is the mainnet API. Real funds on every network.

Ask for a rate, create an exchange, send your funds, and poll until it is finished. $API is the API origin. $KEY is your API key: sign in to the web app and generate it at https://allways.venturalabs.ai/api-access.

Five steps

1. Get a rate with no key.
2. Create the exchange. One credit is spent.
3. Poll every 3 seconds until awaiting_deposit. This usually takes a few seconds, at most about 30. If not, keep polling: it ends as awaiting_deposit or failed (pool_lost or reserve_rejected, credit refunded) within 15 minutes.
4. Send exactly fromAmount from fromAddress to depositAddress before validUntil (usually about 5 minutes ahead). Only a deposit from fromAddress is matched. The network fee is on top. Reporting the transaction is optional and safe right after broadcast. For a subnet token (from=sn<N>), depositAddress is a coldkey: send one transfer_stake on netuid N (origin and destination), not a transfer, from one hotkey that holds all of fromAmount: btcli stake transfer --wallet-name <wallet> --hotkey <hotkey holding fromAmount> --origin-netuid N --dest-netuid N --dest <depositAddress> --amount <fromAmount>. No batch, no proxy, no --all.
5. Poll every 3 seconds until finished, refunded, or failed. Normal order is pending → awaiting_deposit → confirming → exchanging → finished. After a deposit, finishing usually takes a few minutes (chain confirmations). Never stop polling before a terminal status.

The calls

1 · rate

Open call, no key. Returns toAmount, the bounds, and the rungs available right now.

curl "$API/v1/rate?from=sol&to=tao&amount=0.5"

2 · create

Spends one credit. toAmount is final at the 201; depositAddress arrives with the next status.

curl -X POST "$API/v1/exchanges" \
  -H "x-api-key: $KEY" \
  -H "content-type: application/json" \
  -d '{
    "from": "sol",
    "to": "tao",
    "fromAmount": "0.5",
    "fromAddress": "9s4hVRU5nfPF9Er9Y5FexDjxNtvZSYmnVEujxHCX5Gsb",
    "toAddress": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty"
  }'

3 · poll

Every 3 seconds until awaiting_deposit, then read depositAddress and validUntil.

curl "$API/v1/exchanges/5d1f3c2e-8a1b-4c7d-9e0f-123456789abc" -H "x-api-key: $KEY"

4 · sent (optional)

Right after broadcast. Speeds up detection; the scanner finds the deposit without it. A subnet token sent with btcli's MEV shield: post what btcli prints (<block>-<idx>) or the inner transfer hash, not the shield's hash.

curl -X POST "$API/v1/exchanges/5d1f3c2e-8a1b-4c7d-9e0f-123456789abc/sent" \
  -H "x-api-key: $KEY" \
  -H "content-type: application/json" \
  -d '{
    "txHash": "3gU4kPRprSxvLgxjw3NTfLNigddLhx4LJ8JV5jEeyHa3z1TuHHRG1oAy9u9pLdK3zcKQbHD24CyHwGCjijFMCQ7t"
  }'

5 · poll to finished

Every 3 seconds until finished, refunded, or failed. toTxHash is the payout.

{
  "status": "finished",
  "toTxHash": "0x44a05a045015d1caed890ad1f0dd600aedfafb570209c9a093fb296588786480"
}