API v1 · Docs

API v1

Create a stablecoin invoice, send your customer to checkout, and check when it is paid.

Base URLhttps://api.unsu.xyz

JSON over HTTPS

1 · CreateSend an amount and your receiving wallets.

2 · RedirectOpen the returned hosted checkout URL.

3 · ConfirmFulfill only after status becomes PAID.

Authentication

Send your 64-character key from your backend. Never expose it in browser code.

X-API-Key: YOUR_64_CHARACTER_API_KEY
Content-Type: application/json

Create an invoice

POST/v1/invoiceAPI key required

Amount must be at least 1.00 with no more than two decimal places. Include one or more supported wallet addresses. Invoices expire after 25 minutes.

curl -X POST https://api.unsu.xyz/v1/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -d '{
    "amount": "25.00",
    "wallets": {
      "usdt_eth": "0xYOUR_ETHEREUM_ADDRESS",
      "usdc_eth": "0xYOUR_ETHEREUM_ADDRESS",
      "usdc_base": "0xYOUR_BASE_ADDRESS",
      "usds_base": "0xYOUR_BASE_ADDRESS",
      "usdt_tron": "YOUR_TRON_ADDRESS"
    }
  }'

Response

{
  "ok": true,
  "data": {
    "invoice_id": "ABC123DEF4",
    "amount": 25,
    "dust_amount": 0,
    "total": 25,
    "created_at": 1786283648,
    "expires_at": 1786285148,
    "pay_url": "https://pay.unsu.xyz/ABC123DEF4"
  }
}

Redirect your customer to pay_url.

Safe retries: use a unique Idempotency-Key of 8–128 characters for each order. Retrying the same body with the same key returns the original invoice.

Check status

POST/v1/statusAPI key required

Send an invoice ID for full details about one invoice:

curl -X POST https://api.unsu.xyz/v1/status \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"invoice_id":"ABC123DEF4"}'

Response

{
  "ok": true,
  "data": {
    "account": {
      "active": true,
      "expires": 1787786075,
      "used": 42,
      "limit": 500,
      "can_create": true
    },
    "invoice": {
      "invoice_id": "ABC123DEF4",
      "status": "PAID",
      "amount": 25,
      "dust_amount": 0,
      "tx_hash": "0x…",
      "paid_at": 1786284012,
      "created_at": 1786283648,
      "expires_at": 1786285148
    }
  }
}

Send no body to receive your account usage and a map of invoice statuses from the last 24 hours.

Recent-status response

{
  "ok": true,
  "data": {
    "account": {
      "active": true,
      "used": 42,
      "limit": 500,
      "can_create": true
    },
    "invoices": {
      "ABC123DEF4": "PAID",
      "GHT567JKL8": "PENDING"
    },
    "window_hours": 24
  }
}

Accepted payments

Ethereumusdt_eth · usdc_eth

Baseusdc_base · usds_base

TRONusdt_tron

Ethereum and Base addresses use 0x plus 40 hexadecimal characters. TRON uses a valid 34-character, T-prefixed address.

Invoice statuses

PENDINGWaiting for valid payment.

PAIDPayment confirmed.

EXPIREDPayment window ended.

Integration rules

Create and store your order first.
Use your order ID as the idempotency key.
Store the returned invoice ID.
Redirect the customer to the hosted checkout.
Poll /v1/status every 15 seconds when expecting a payment, and stop when the status is PAID or EXPIRED.
Fulfill only when the status is PAID.
Create a fresh invoice if it becomes EXPIRED.

Errors

400Invalid request, amount, wallet, invoice ID, or idempotency key.
401Missing or invalid API key.
402Subscription inactive or invoice limit reached.
404Endpoint or merchant-owned invoice not found.
409Idempotency key reused with different request data.
429Rate limit exceeded; respect Retry-After.
500Unexpected server error.

Health check

GET/healthzPublic

curl https://api.unsu.xyz/healthz