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 balance to fiat and sends it to a saved payout account

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.

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} to track processingStages until the conversion settles.

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();
/*
{
  amount:          100,
  amountUSD:       100.00,
  fee:             0.5,
  feeUSD:          0.50,
  amountAfterFee:  99.5,
  estimatedOutput: 1.24,
  rate:            0.0125
}
*/

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._id;
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["_id"]

Step 2 (alt) — Create a fiat conversion

To convert to fiat, supply a payoutAccountId instead of toChain/toCoin.

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

async function pollConversion(id, intervalMs = 8000) {
  while (true) {
    const res  = await fetch(`${BASE}/conversions/${id}`, { headers: makeHeaders() });
    const { data } = await res.json();
    const stages = data.processingStages;

    console.log('Stages:', stages);

    const allDone = Object.values(stages).every(s => s.status === 'completed');
    if (allDone) return data;

    const failed = Object.values(stages).find(s => s.status === 'failed');
    if (failed) throw new Error('Conversion failed');

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

import time

def poll_conversion(conversion_id, interval_s=8):
    while True:
        res    = requests.get(f"{BASE}/conversions/{conversion_id}", headers=make_headers())
        data   = res.json()["data"]
        stages = data["processingStages"]

        if all(s["status"] == "completed" for s in stages.values()):
            return data
        if any(s["status"] == "failed" for s in stages.values()):
            raise RuntimeError("Conversion failed")

        time.sleep(interval_s)

Processing stages

Stage	What happens
`sendForConversion`	Funds sent to the conversion provider
`conversionState`	Provider executes the swap
`settleCrypto`	Converted funds delivered to destination

Error handling

Scenario	Action
Amount below minimum	Check `fee.amountAfterFee > 0` before creating
Unsupported swap pair	Verify pair exists via `/conversions/swap-chains` and `/conversions/swap-coins`
Stage `status: "failed"`	Read the stage’s `lastError` field; retry or contact support

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