Conversions

A conversion moves funds from one form to another without requiring the customer to make a new payment. There are two types:

Type	What it does
`crypto`	Swaps a coin on one chain to a different coin or chain (e.g. USDT/Ethereum → SOL/Solana)
`fiat`	Converts crypto and sends it to one of your saved payout accounts (a bank account, or a crypto account)

A crypto conversion always settles to your own merchant wallet on the destination chain. Tender picks the conversion route automatically. A conversion must be worth more than $20 USD.

How it works

Discover supported swap chains and coins

Call GET /conversions/swap/chains and GET /conversions/swap/coins to find what source/destination pairs are available.

Check the fee

Call GET /conversions/fee/{chain}/{coin}/{amount} to get a fee quote and estimated output before committing. For crypto swaps, pass toChain and toCoin as query params to get a destination-specific estimate. For fiat, pass toChain=fiat and the fiat currency as toCoin.

Create the conversion

Call POST /conversions with the source coin, chain, amount, and destination. The conversion is queued immediately and processed asynchronously.

Poll for completion

Call GET /conversions/{id} until status is completed or failed. There are no conversion webhooks, so polling is the only way to track progress.

Prerequisites

Authentication guide

These endpoints use Signed (HMAC) authentication — an HMAC-SHA256 signature is required on every request. See the authentication guide for code examples.

const BASE = 'https://sandbox-api.tender.cash/v1/api';
// makeHeaders() → { 'x-access-id', 'x-request-id', 'x-timestamp', 'authorization', ... }

Step 1 — Check the fee

Always fetch a fee quote before creating a conversion so you can show the cost to the user.

// Crypto swap fee quote
const feeRes = await fetch(
  `${BASE}/conversions/fee/ethereum/usdt/100?toChain=solana&toCoin=sol`,
  { headers: makeHeaders() }
);
const { data: fee } = await feeRes.json();
/*
{
  from: { chain: "ethereum", currency: "usdt", symbol: "USDT", amount: 100, amountUSD: 100 },
  to:   { chain: "solana", currency: "sol", symbol: "SOL", amount: 0.6633, amountUSD: 99.5 },
  fee:  { fee: 0.5, feeUSD: 0.5 },
  rate: { value: "0.006667", perSourceUnit: "0.006700", symbol: "SOL", overridden: false }
}
*/
console.log(`You pay ${fee.from.amount} ${fee.from.symbol}, receive ~${fee.to.amount} ${fee.to.symbol}`);

fee_res = requests.get(
    f"{BASE}/conversions/fee/ethereum/usdt/100",
    params={ "toChain": "solana", "toCoin": "sol" },
    headers=make_headers(),
)
fee = fee_res.json()["data"]

Step 2 — Create a crypto swap

const convRes = await fetch(`${BASE}/conversions`, {
  method: 'POST',
  headers: makeHeaders(),
  body: JSON.stringify({
    type:    'crypto',
    chain:   'ethereum',
    coin:    'usdt',
    amount:  '100',
    toChain: 'solana',
    toCoin:  'sol',
  }),
});

const { data } = await convRes.json();
const conversionId = data.conversion.conversionId;
console.log('Status:', data.conversion.status); // "pending"

conv_res = requests.post(
    f"{BASE}/conversions",
    headers=make_headers(),
    json={
        "type":    "crypto",
        "chain":   "ethereum",
        "coin":    "usdt",
        "amount":  "100",
        "toChain": "solana",
        "toCoin":  "sol",
    },
)
conversion = conv_res.json()["data"]["conversion"]
conversion_id = conversion["conversionId"]

Step 2 (alt) — Create a fiat conversion

To convert to fiat, supply a payoutAccountId instead of toChain/toCoin. It must be one of your saved, active payout accounts. If it is a crypto payout account, the converted funds are sent to its address instead.

const convRes = await fetch(`${BASE}/conversions`, {
  method: 'POST',
  headers: makeHeaders(),
  body: JSON.stringify({
    type:            'fiat',
    chain:           'ethereum',
    coin:            'usdt',
    amount:          '100',
    payoutAccountId: '66aec7de809b7f45c42a49f9',
  }),
});

conv_res = requests.post(
    f"{BASE}/conversions",
    headers=make_headers(),
    json={
        "type":            "fiat",
        "chain":           "ethereum",
        "coin":            "usdt",
        "amount":          "100",
        "payoutAccountId": "66aec7de809b7f45c42a49f9",
    },
)

Step 3 — Poll for completion

// Conversion endpoints share 10 requests/minute, so poll every 10s or slower.
async function pollConversion(id, intervalMs = 15000) {
  while (true) {
    const res  = await fetch(`${BASE}/conversions/${id}`, { headers: makeHeaders() });
    const { data } = await res.json();

    console.log('Status:', data.status, 'Stages:', data.processingStages);

    if (data.status === 'completed') return data;
    if (data.status === 'failed') throw new Error(`Conversion failed: ${data.failureReason}`);

    await new Promise(r => setTimeout(r, intervalMs));
  }
}

import time

# Conversion endpoints share 10 requests/minute, so poll every 10s or slower.
def poll_conversion(conversion_id, interval_s=15):
    while True:
        res  = requests.get(f"{BASE}/conversions/{conversion_id}", headers=make_headers())
        data = res.json()["data"]

        if data["status"] == "completed":
            return data
        if data["status"] == "failed":
            raise RuntimeError(f"Conversion failed: {data.get('failureReason')}")

        time.sleep(interval_s)

Processing stages

processingStages shows progress in more detail. Use the top-level status to decide when the conversion is finished.

Stage	What happens	Statuses
`sendForConversion`	Funds are sent for conversion	`pending`, `initiated`, `executed`, `completed`, `failed`
`conversionState`	The conversion is executed	`pending`, `executed`, `completed`, `failed`
`settleCrypto`	Converted funds are settled	`pending`, `executed`, `completed`, `failed`
`settleFiat`	Fiat is paid out to the bank account (fiat conversions only)	`pending`, `processed`, `completed`, `failed`

To get the on-chain transactions behind the stages, with their hashes, call List Conversion Internal Transactions. The conversion_send entry is the send that funds the conversion.

Error handling

Scenario	Action
`Conversion request must be more than $20 USD`	Increase the amount; check `from.amountUSD` from the fee endpoint
Unsupported swap pair	Verify the pair via `/conversions/swap/chains` and `/conversions/swap/coins`
`Invalid or inactive payout account`	Use the ID of one of your active payout accounts
HTTP 500 `Failed to create conversion`	The pair could not be priced; re-check it with the fee endpoint and retry
`status: "failed"`	Read `failureReason` on the conversion; retry or contact support
HTTP 429	Conversion endpoints share 10 requests/minute; slow down. See Rate limits

Getting started

Online payments

Subwallets

Webhooks

How it works

Prerequisites

Authentication guide

Step 1 — Check the fee

Step 2 — Create a crypto swap

Step 2 (alt) — Create a fiat conversion

Step 3 — Poll for completion

Processing stages

Error handling

​How it works

​Prerequisites

Authentication guide

​Step 1 — Check the fee

​Step 2 — Create a crypto swap

​Step 2 (alt) — Create a fiat conversion

​Step 3 — Poll for completion

​Processing stages

​Error handling

How it works

Prerequisites

Step 1 — Check the fee

Step 2 — Create a crypto swap

Step 2 (alt) — Create a fiat conversion

Step 3 — Poll for completion

Processing stages

Error handling