Crypto↔Crypto

Show deposit address, wait for on-chain funds, display balance in less than 1 day

Summary

Create a Customer, provision a custodial wallet, show the deposit address to the user ("waiting for deposit"), then surface funds once detected. Use webhooks for notifications and always re-verify via REST before updating UI. Today, balances reflect USDC only.

Problem → Solution mapping

Pain point	Capability	Mechanism
Need deposit address instantly	Customers + Wallet API	POST /v1/customers then POST /v1/customers/{id}/wallets → wallets[...]
Show "awaiting deposit"	UI + polling	Display address/QR; poll GET /balances
Push updates to app	Webhooks	Subscribe, validate HMAC; then REST re-verify
Accurate final state	REST as truth	GET /v1/customers/{id}/balances before UI change

Architecture

Implementation steps

Create user

curl https://wallet.swipelux.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"+1234567890",
    "birthDate":"1990-01-01",
    "residentialAddress":{"streetLine1":"123 Main St","city":"San Francisco","state":"CA","postalCode":"94101","country":"US"},
    "identifyingInformation":[{"type":"drivers_license","issuingCountry":"US",
      "frontSideImage":"data:image/png;base64,iVBORw0KGgoAAA...","backSideImage":"data:image/png;base64,iVBORw0KGgoBBB..."}]
  }'

Response (truncated):

{
  "id":"cus_cK69MttD5nAUAbud1B",
  "status":"approved"
}

Provision wallet

curl https://wallet.swipelux.com/v1/customers/cus_cK69MttD5nAUAbud1B/wallets \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{ "chains": ["base"] }'

Show wallet to end user + "waiting for deposit"

Poll the customer's balance from your server to avoid exposing API keys in the browser. Expose an endpoint like /api/balances that your frontend can call while showing "waiting for deposit".

const express = require('express');
const fetch = require('node-fetch');
const app = express();
 
app.get('/api/balances', async (req, res) => {
  const customer = req.query.customer;
  const r = await fetch(`https://wallet.swipelux.com/v1/customers/${customer}/balances`, {
    headers: {
      'X-API-Key': process.env.SWIPELUX_API_KEY,
      'Content-Type': 'application/json',
    },
  });
  const data = await r.json();
  res.json({ balance: data.usdc?.available ?? 0 });
});

Pull data or wait for webhook to update UI

Subscribe webhook URL and store the secret key:

curl https://wallet.swipelux.com/v1/webhooks \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{ "url": "https://your-domain.com/webhook" }'

Node.js HMAC-SHA256 verification + REST re-check:

const crypto = require('crypto');
const express = require('express');
const fetch = require('node-fetch');
const app = express();
 
app.post('/webhook', express.raw({type:'application/json'}), async (req, res) => {
  const sig = req.header('X-Webhook-Signature') || '';
  const secretKey = process.env.WEBHOOK_SECRET_KEY; // from PATCH response
  const expected = crypto.createHmac('sha256', secretKey).update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig,'hex'), Buffer.from(expected,'hex'))) {
    return res.status(401).end();
  }
  const evt = JSON.parse(req.body.toString('utf8'));
  // Examples: transfer.completed, transfer.updated (if emitted on deposit)
  if (evt.type && evt.type.startsWith('transfer.')) {
    // Re-verify via REST before updating UI
    const trId = evt.data?.id;
    if (trId) {
      const r = await fetch(`https://wallet.swipelux.com/v1/transfers/${trId}`, {
        headers: {
          'X-API-Key': process.env.SWIPELUX_API_KEY,
          'Content-Type': 'application/json'
        }
      });
      const tr = await r.json();
      // Optionally also read the customer balance to drive UI
    }
  }
  res.sendStatus(200);
});

Show the balance (REST is source of truth)

curl https://wallet.swipelux.com/v1/customers/cus_cK69MttD5nAUAbud1B/balances \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'

Sample response:

{ "balance": 48.5 }

Display balance to the user. It represents total net worth across all supported networks in USD terms (per docs).

Set URL via PATCH /v1/webhooks; store secretKey.

Validate X-Webhook-Signature using HMAC-SHA256 over the raw body.

Always re-fetch via REST (GET /v1/customers/{id}/balances, and GET /v1/transfers/{id} if a transfer event is referenced) before updating UI or ledgers.

UX notes

Show address + QR and a deterministic "Waiting for deposit…" state.

Use polling (e.g., 5s backoff) until webhook arrives, then switch to REST-confirmed balance.

KPIs

Time from address display → first positive balance.

% deposits recognized without manual refresh.

Webhook validation success rate.

Note: If a webhook is missed, polling balances is sufficient to update UI.

On this page