404.cash API

Quick Start

Get a swap widget running on your site in 3 steps:

1. Create an account

Register at dash.404.cash to get your API key and widget key.

2. Embed the widget

<div id="swap-widget"></div>
<script src="https://swap.404.cash/widget.js"
  data-widget-key="wk_your_key_here"
  data-element="#swap-widget"
  data-theme="dark">
</script>

3. Receive webhooks

Configure a webhook URL in your dashboard to get notified when swaps complete. All webhooks are signed with HMAC-SHA256.

Authentication

All API requests require an X-API-Key header with your merchant API key.

curl -H "X-API-Key: mk_your_api_key_here" \
  https://api.404.cash/v1/merchant/profile

API keys are generated in the dashboard under API Keys. You can create multiple keys and revoke them independently.

Embed Widget

The swap widget is a self-contained JavaScript bundle hosted at swap.404.cash. It renders inside any container element.

Basic embed

<div id="swap-widget"></div>
<script src="https://swap.404.cash/widget.js"
  data-widget-key="wk_your_key_here"
  data-element="#swap-widget">
</script>

Iframe embed

<iframe
  src="https://swap.404.cash/?key=wk_your_key_here&theme=dark"
  width="420" height="600"
  style="border: none; border-radius: 16px;">
</iframe>

Widget Configuration

Configure your widget via data attributes or query parameters:

Bring Your Own Keys (BYOK)

Pro and Max merchants can use their own exchange API keys for direct provider access, better rates, and higher limits.

Configure BYOK keys in the dashboard under Widget Settings. Keys are transmitted via internal service bindings — never exposed publicly.

Merchant Profile

{
  "id": "mc_abc123",
  "name": "My Project",
  "email": "me@example.com",
  "plan": "pro",
  "quota_balance_usd": 42.50,
  "referral_code": "ref_xyz",
  "webhook_url": "https://example.com/webhook",
  "created_at": 1711900000
}

Widgets

{
  "widget_key": "wk_abc123def456"
}

{
  "widgets": [
    {
      "id": "wk_abc123",
      "label": "Main Widget",
      "theme": "dark",
      "from_tickers": ["btc", "eth"],
      "to_tickers": ["xmr"],
      "created_at": 1711900000
    }
  ]
}

{
  "ok": true
}

Swaps

{
  "swaps": [
    {
      "id": "sw_abc123",
      "from_ticker": "btc",
      "to_ticker": "xmr",
      "amount_from": 0.01,
      "status": "finished",
      "engine": "changenow",
      "widget_id": "wk_abc123",
      "created_at": 1711900000
    }
  ],
  "total": 1
}

{
  "total": { "swaps": 150, "volume_usd": 12500.00 },
  "last_24h": { "swaps": 5, "volume_usd": 420.00 },
  "by_status": [
    { "status": "finished", "count": 120 },
    { "status": "pending", "count": 15 },
    { "status": "failed", "count": 10 },
    { "status": "expired", "count": 5 }
  ]
}

Quota & Billing

{
  "deposit_id": "dep_abc123",
  "amount_usd": 10.00,
  "pay_address": "TXyz...abc",
  "pay_amount": 10.00,
  "chain": "tron",
  "currency": "USDT",
  "status": "pending",
  "expires_at": 1711986400
}

{
  "per_swap_usd": 0.10,
  "min_deposit_usd": 5,
  "chains": ["tron", "bsc", "polygon"]
}

Webhook Test

{
  "ok": true
}

Webhook Events

When a swap changes status, 404.cash sends a POST request to your configured webhook URL with the following payload:

{
  "event": "swap.status_changed",
  "swap": {
    "id": "sw_abc123",
    "status": "finished",
    "from_ticker": "btc",
    "to_ticker": "xmr",
    "amount_from": 0.01,
    "widget_id": "wk_abc123",
    "created_at": 1711900000
  }
}

Event types

Webhook Verification

All webhooks include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  const raw = JSON.stringify(req.body);

  if (!verifyWebhook(raw, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, swap } = req.body;
  console.log(`Swap ${swap.id} → ${swap.status}`);
  res.status(200).send('OK');
});

Plans & Rate Limits

Plans can also be unlocked by volume: $500K total for Pro, $5M total for Max (auto-upgrade).

Error Codes

All errors return a JSON object with an error field:

{
  "error": "Invalid API key"
}

Swap Statuses