Chains and tokens¶

Every invoice, payment, balance and withdrawal names a chainId and a tokenId. Both are NullSwap UUIDs, not chain-native identifiers — there is no route anywhere that takes "ethereum" or 1 or a contract address in place of them. These two endpoints are how you turn what you know into the ids you need.

Chains¶

curl "https://api.pay.nullswap.com/api/v1/chains?type=EVM" \
  -H "x-api-key: sk_live_..."

{
  "data": [
    {
      "id": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "name": "Ethereum",
      "networkChainId": 1,
      "type": "EVM",
      "logoURI": "https://cdn.pay.nullswap.com/chains/ethereum.svg",
      "priority": 10,
      "confirmationBlocks": 12,
      "latestBlockNumber": 21345678,
      "explorerTxUrlTemplate": "https://etherscan.io/tx/{value}",
      "explorerAddressUrlTemplate": "https://etherscan.io/address/{value}",
      "standard": "ERC20"
    }
  ]
}

Filters: id, type, name. All repeatable, all exact matches — name is compared case-insensitively but is not a substring search, so name=Ethereum works and name=eth returns nothing.

The response is { "data": [...] } with no pagination object — the list is short and complete, and offset/limit are refused with 400 INVALID_QUERY_PARAMETER if you send them.

latestBlockNumber is the only field here that moves minute to minute; everything else is stable enough to cache for hours. Pairing it with the blockNumber on a payment tells you how deep that payment is right now:

depth = chain.latestBlockNumber - payment.blockNumber + 1

You have to compute the depth yourself: confirmations on a payment is a snapshot from when the record was last written, not a live counter.

On RIPPLE, the XRP Ledger, a block is a ledger: latestBlockNumber and a payment's blockNumber are ledger indexes, and only ledgers the network has validated are read. The coin is XRP with decimals: 6, so "1000000" is 1 XRP. A deposit there is named by an address and a destination tag — see invoices.

Tokens¶

curl "https://api.pay.nullswap.com/api/v1/tokens?symbol=USDT&status=ENABLED" \
  -H "x-api-key: sk_live_..."

{
  "data": [
    {
      "id": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "chain": {
        "id": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "name": "Ethereum",
        "networkChainId": 1,
        "type": "EVM",
        "logoURI": "https://cdn.pay.nullswap.com/chains/ethereum.svg",
        "priority": 10,
        "confirmationBlocks": 12,
        "latestBlockNumber": 21345678,
        "explorerTxUrlTemplate": "https://etherscan.io/tx/{value}",
        "explorerAddressUrlTemplate": "https://etherscan.io/address/{value}",
        "standard": "ERC20"
      },
      "currency": {
        "id": "7d8e9f0a-1b2c-4d3e-8f40-5a6b7c8d9e0f",
        "name": "Tether USD",
        "symbol": "USDT",
        "logoURI": "https://cdn.pay.nullswap.com/tokens/usdt.svg",
        "decimals": 6,
        "priority": 20
      },
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "type": "ERC20",
      "category": "HEDGE",
      "maxAmountOut": "100000000000",
      "decimals": 6,
      "price": "1000200000000000000",
      "status": "ENABLED",
      "srcStatus": "ENABLED",
      "dstStatus": "ENABLED",
      "monitoringCode": "usdt_eth"
    }
  ]
}

Each token embeds its whole chain, so one call gives you everything you need to render a picker without joining anything yourself. Also unpaginated.

Different filters are ANDed; repeated values of one filter are ORed. So ?chainId=A&chainId=B&status=ENABLED means (chain A or chain B) and enabled.

Currency versus token¶

A currency is the asset as a human names it — "Tether USD", USDT, 6 decimals. A token is that currency deployed on one chain at one address. USDT on Ethereum and USDT on Tron are two tokens sharing one currency.id.

Invoices, balances and withdrawals all address the token. currency.id is only useful for grouping in your own UI.

The other fields¶

price is a reference rate for display and conversion. It is not what an invoice is settled at — raise an invoice and NullSwap fixes the amount at creation time.

Creating an invoice in a token whose srcStatus is DISABLED is rejected with 422 TOKEN_IS_DISABLED. Disabling stops new invoices only: a payment that arrives in the token afterwards — on an invoice raised earlier, or on a static wallet — is still recorded and swept.

Rates¶

curl "https://api.pay.nullswap.com/api/v1/tokens/rate?srcTokenId=3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908&dstTokenId=8c1f2e3d-4a5b-4c6d-8e70-9f0a1b2c3d4e&amountIn=250000000" \
  -H "x-api-key: sk_live_..."

{
  "srcToken": { "id": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908", "…": "full token object" },
  "dstToken": { "id": "8c1f2e3d-4a5b-4c6d-8e70-9f0a1b2c3d4e", "…": "full token object" },
  "rate": "396560000000000",
  "minAmountIn": "10000000",
  "maxAmountIn": "4180000000",
  "maxAmountOut": "1608910000000000000",
  "amountIn": "250000000",
  "amountOut": "99140000000000000",
  "hedgeAmountIn": "248747000"
}

Pass an amount and you get a quote for exactly that amount: amountIn and amountOut are both filled, and amountOut is what that amount pays out with every fee already deducted — the platform's and, for a pair that converts through a liquidity pool, the pool's fee and the price impact of your amount on it. You do not subtract anything yourself. With amountOut instead, the amountIn that comes back is rounded up, so it pays out at least the amountOut you asked for.

rate is amountOut / amountIn with the decimals aligned, so

amountOut ≈ amountIn × rate × 10^(dstDecimals − srcDecimals) / 10^18

reproduces a quote up to rounding. Use amountOut itself when you have it.

maxAmountIn and maxAmountOut follow the liquidity available for the pair and what we can pay out in dstTokenId at the moment, so they move with the market and can be much lower than the USD maximum for a thinly traded token. Read them from the same response you quote from rather than from an earlier one.

TOKENS_RATE_NOT_FOUND means the pair cannot be priced: one of the tokens does not exist or has no price yet, the pair is not supported, or the liquidity data for it is temporarily unavailable. The last case clears up on its own, so a pair that worked a minute ago is worth retrying. See Errors for the envelope.

The rate does not look at srcStatus or dstStatus: a pair with a DISABLED token is still quoted. Check the statuses on the token before you offer it.

Caching¶

Fetch both lists at start-up and refresh them on a timer rather than calling them on the path of every checkout. The one thing not to cache indefinitely is a token id you have never seen before — if TOKEN_NOT_FOUND comes back on an invoice you expected to work, refresh the list before treating it as an error.