Back

Public API

Developer Docs

Build against WaifuSwap quote, swap, token, and order-status endpoints. XMR routes use the curated xmr_supported token list. All responses use the same envelope: success, data, and message.

Base URLhttps://api.waifuswap.net
Important: quote amounts and deposit instructions should be treated as time-sensitive. Always create a fresh quote before creating a swap, and send users to the returned order URL for status.

Integration checklist

  • Use /public/v1/tokens to build selectors instead of hardcoding token and chain pairs.
  • Use /public/v1/estimate only for live form math. It does not create an order.
  • Create a fresh /public/v1/quote before calling /public/v1/swap because amounts and deadlines are time-sensitive.
  • When either side is XMR, only use assets where xmr_supported is true. XMR routes are input-amount based.
  • Store the returned order_url and send users to that page for status tracking.

Status meanings

PENDINGThe order exists and is waiting for the required deposit.
PROCESSINGFunds or routing activity have been detected and the swap is still moving.
SUCCESSThe swap completed successfully.
FAILEDThe swap could not be completed. If funds were sent, the refund path should be used.
EXPIREDThe quote or deposit window expired before completion.
GET/public/v1/tokens

Supported Tokens

Returns supported assets grouped by network. Use this to populate token selectors and resolve ticker/chain pairs.

Response
{
  "success": true,
  "data": [
    {
      "name": "Ethereum",
      "tokens": [
        {
          "ticker": "ETH",
          "name": "Ethereum",
          "decimals": 18,
          "chain": "eth",
          "price": 3000,
          "icon_url": "",
          "xmr_supported": false
        }
      ]
    }
  ]
}
POST/public/v1/estimate

Live Estimate

Preview the opposite amount while a user is editing the swap form. This does not create an order.

Request
{
  "from_ticker": "ETH",
  "from_net": "eth",
  "to_ticker": "USDT",
  "to_net": "eth",
  "amount": "1",
  "amount_out": "",
  "slippage": "0.5"
}
Response
{
  "success": true,
  "data": {
    "amount_in": "1",
    "amount_out": "3000",
    "swap_type": "FLEX_INPUT",
    "app_fees": [{ "fee": 50 }]
  }
}
POST/public/v1/quote

Quote

Creates a review quote using the selected pair, amount, recipient address, refund address, and slippage.

Request
{
  "from_ticker": "ETH",
  "from_net": "eth",
  "to_ticker": "USDT",
  "to_net": "eth",
  "amount": "1",
  "recipient": "0xRecipientAddress",
  "refund_addr": "0xRefundAddress",
  "slippage": "0.5"
}
Response
{
  "success": true,
  "data": {
    "from_token": { "ticker": "ETH", "chain": "eth" },
    "to_token": { "ticker": "USDT", "chain": "eth" },
    "amount_in": "1",
    "amount_out": "3000",
    "atomic_amount": "1000000000000000000",
    "slippage_bps": 50,
    "swap_type": "FLEX_INPUT"
  }
}
POST/public/v1/swap

Create Swap

Confirms a reviewed quote and returns an encrypted order token plus an order page URL.

Request
{
  "from_ticker": "ETH",
  "from_net": "eth",
  "to_ticker": "USDT",
  "to_net": "eth",
  "atomic_amount": "1000000000000000000",
  "amount_in": "1",
  "amount_out": "3000",
  "recipient": "0xRecipientAddress",
  "refund_addr": "0xRefundAddress",
  "slippage_bps": 50,
  "swap_type": "FLEX_INPUT"
}
Response
{
  "success": true,
  "data": {
    "order_token": "encrypted-order-token",
    "order_url": "/order/encrypted-order-token"
  }
}
GET/public/v1/orders/{order_token}

Order Status

Returns deposit instructions and sanitized order status for an encrypted order token.

Response
{
  "success": true,
  "data": {
    "order": {
      "deposit_address": "0xDepositAddress",
      "deposit_memo": "",
      "from_ticker": "ETH",
      "to_ticker": "USDT",
      "amount_in": "1",
      "amount_out": "3000"
    },
    "status": { "status": "PENDING" },
    "step": 0,
    "terminal": false
  }
}
Error format: failed responses keep the same envelope and return success: false with a human-readable message. Clients should display the message and avoid retry loops for expired quotes, unsupported routes, or invalid addresses.
Swap flow overviewPrivacy and liquidity notes