API

Swaps for your app, in three calls

The same API this site runs on. Best price from ChangeNOW and SideShift, start a swap, follow it to the end. Free, no key, works from any website.

No keyJSON83 coinsNon-custodial

Quick start

Three calls take a user from a price to coins in their wallet.

  1. 1
    Get a priceBoth services are asked, the best amount wins.GET/quote
  2. 2
    Start the swapSend the user's address, get a deposit address back.POST/swaps
  3. 3
    Follow itAsk for the status until it says finished.GET/swaps/{id}
# 1. price
curl "https://hoppu.io/api/v1/quote?from=btc&to=xmr&amount=0.01"

# 2. start the swap
curl -X POST "https://hoppu.io/api/v1/swaps" \
  -H "Content-Type: application/json" \
  -d '{"from":"btc","to":"xmr","amount":0.01,
       "address":"YOUR_XMR_ADDRESS"}'

# 3. follow it
curl "https://hoppu.io/api/v1/swaps/4f9k2mq8xa"

Try it

Live prices

A real request to GET /quote. Pick two coins and press Send.

from
to
GET
Press Send to ask both services for a live price.

Endpoints

GET/coins

List coins

Every coin you can swap, with the id you use in the other calls, its ticker, network and the name of its memo field if it has one.

curl "https://hoppu.io/api/v1/coins"
200Response
{
  "coins": [
    {
      "id": "usdt-trc20",
      "sym": "USDT",
      "name": "Tether",
      "net": "TRON",
      "memo": null,
      "label": "USDT (TRON)"
    },
    ...
  ]
}
GET/quote

Get the best price

Asks both swap services and returns the best amount plus every offer. Amounts are whole coins with every fee already taken out. Cached for 20 seconds.

Query parameters
fromstringrequired

Coin id you send, e.g. btc

tostringrequired

Coin id you get

amountnumberrequired

Amount you send, in whole coins

Below the minimum you get HTTP 400 with min in the body, so you can show it.

curl "https://hoppu.io/api/v1/quote?from=btc&to=xmr&amount=0.01"
200Response
{
  "from": "btc",
  "to": "xmr",
  "amount": 0.01,
  "best": {
    "provider": "changenow",
    "name": "ChangeNOW",
    "receive": 1.2289,
    "eta": "1-15"
  },
  "offers": [
    { "provider": "changenow", "receive": 1.2289 },
    { "provider": "sideshift", "receive": 1.2241 }
  ],
  "min": 0.00017,
  "rate": 122.89
}
POST/swaps

Start a swap

Starts the swap with the best service (and falls back to the next one if it refuses). Show your user the deposit address it returns.

JSON body
fromstringrequired

Coin id you send

tostringrequired

Coin id you get

amountnumberrequired

Planned amount. The final one is whatever arrives.

addressstringrequired

Where the coins are paid out

extrastringoptional

Memo or tag for the payout, only for coins that use one

refundstringoptional

Where the coins go back if the swap fails

Your user sends amountFrom to depositAddress (plus depositExtra when it is set). People can follow it at https://hoppu.io/order/{id}.

curl -X POST "https://hoppu.io/api/v1/swaps" \
  -H "Content-Type: application/json" \
  -d '{"from":"btc","to":"xmr","amount":0.01,"address":"YOUR_XMR_ADDRESS"}'
200Response
{
  "id": "4f9k2mq8xa",
  "status": "waiting",
  "provider": "ChangeNOW",
  "from": { "id": "btc", "sym": "BTC", "memo": null },
  "to": { "id": "xmr", "sym": "XMR", "memo": null },
  "amountFrom": "0.01",
  "amountTo": "1.2289",
  "depositAddress": "bc1q...",
  "depositExtra": null,
  "payoutAddress": "4AdUndXHHZ...",
  "createdAt": 1795000000000
}
GET/swaps/{id}

Follow a swap

The swap with its live status, amounts and transaction hashes. Ask at most every 10 seconds.

Path
idstringrequired

The id from POST /swaps

curl "https://hoppu.io/api/v1/swaps/4f9k2mq8xa"
200Response
{
  "id": "4f9k2mq8xa",
  "status": "finished",
  "amountFrom": "0.01",
  "amountTo": "1.2274",
  "depositHash": "8c1e...f02a",
  "payoutHash": "b7d4...91ce",
  "updatedAt": 1795000420000
}

Reference

Swap statuses

Every swap walks through these in order. Show them as steps to your user.

  1. 1waitingWaiting for the deposit
  2. 2confirmingDeposit seen, confirming
  3. 3exchangingBeing exchanged
  4. 4sendingPaying out
  5. finishedDone, payoutHash is set
It can also end asfailedrefundedexpired(no deposit in time)

Errors and limits

400
Bad requestSomething in the request is off, or the amount is under the minimum (the body has min).
404
Not foundNo swap with that id.
429
Slow downPer IP: 60 quotes a minute, 10 new swaps per 10 minutes, 120 status checks a minute.
503
Services busyThe swap services are not answering right now. Try again in a minute.

Errors always come as { "error": "A sentence you can show to people" }. Need higher limits or your own fee? support@hoppu.io

Coin ids

Click one to copy it
btcBitcoinBitcoin
ethEthereumEthereum
xmrMoneroMonero
usdt-trc20TetherTRON
usdt-erc20TetherEthereum
usdt-bscTetherBNB Chain
usdt-solTetherSolana
usdcUSD CoinEthereum
usdc-solUSD CoinSolana
solSolanaSolana
ltcLitecoinLitecoin
bnbBNBBNB Chain
trxTRONTRON
xrpXRPXRP LedgerDestination tag
dogeDogecoinDogecoin
adaCardanoCardano
avaxAvalancheC-Chain
polPolygonPolygon
linkChainlinkEthereum
shibShiba InuEthereum
bchBitcoin CashBitcoin Cash
xlmStellarStellarMemo
zecZcashZcash
dashDashDash
nearNEARNEAR
atomCosmosCosmos HubMemo
arbArbitrumArbitrum
opOptimismOptimism
pepePepeEthereum
uniUniswapEthereum
etcEthereum ClassicEthereum Classic
kasKaspaKaspa
suiSuiSui
aptAptosAptos
hbarHederaHederaMemo
daiDaiEthereum
dotPolkadotPolkadot
eth-baseEthereumBase
eth-arbEthereumArbitrum
eth-opEthereumOptimism
usdc-baseUSD CoinBase
usdc-arbUSD CoinArbitrum
usdc-polUSD CoinPolygon
usdc-bscUSD CoinBNB Chain
usdt-polTetherPolygon
usdt-arbTetherArbitrum
usdt-tonTetherTONMemo
hypeHyperliquidHyperEVM
taoBittensorBittensor
sSonicSonic
beraBerachainBerachain
tiaCelestiaCelestiaMemo
algoAlgorandAlgorandNote
stxStacksStacksMemo
icpInternet ComputerICP
strkStarknetStarknet
xtzTezosTezos
filFilecoinFilecoin
vetVeChainVeChain
xdcXDC NetworkXDC
dcrDecredDecred
egldMultiversXMultiversX
wifdogwifhatSolana
bonkBonkSolana
trumpOfficial TrumpSolana
jupJupiterSolana
flokiFlokiEthereum
aaveAaveEthereum
ondoOndoEthereum
enaEthenaEthereum
fetArtificial SuperintelligenceEthereum
wldWorldcoinEthereum
ldoLido DAOEthereum
crvCurveEthereum
grtThe GraphEthereum
imxImmutableEthereum
apeApeCoinEthereum
sandThe SandboxEthereum
manaDecentralandEthereum
batBasic Attention TokenEthereum
compCompoundEthereum
snxSynthetixEthereum
cakePancakeSwapBNB Chain