CoinsSend API Documentation

This documentation covers the verified public merchant integration and checkout contract. Start with the machine-readable OpenAPI 3.1 document for agent/tool integration and use the narrative guides for operational detail.

Guides

• Supported Coins & Networks
• Getting Started
• Authentication and signature vectors
• API Reference
• Invoices
• Withdrawals
• Static Wallets
• Merchant balances and fees
• Coin rates and live catalog
• Webhooks
• Error Handling
• Rate Limits and Safe Retries
• Server-side examples
• AI integration prompts

Public Allowlist

Authenticated merchant operations:

• POST /v1/invoices
• POST /v1/withdrawals
• GET /v1/merchants/balances
• GET /v1/merchants/fees
• POST /v1/wallet-address

Public discovery and checkout operations:

• GET /v1/get-coin-rate
• GET /v1/coins-and-fee
• GET /v1/invoices/{invoiceCode}
• POST /v1/invoices/{invoiceCode}/provider-card-orders
• GET /v1/wallet-addresses/{walletAddress}/qr

Only the operations listed above are part of the supported public integration contract.

Authentication Summary

Merchant operations require Merchant and Sign. Withdrawal submission also requires a fresh Timestamp (X-Timestamp is accepted as an alias).

The request signature uses the server-canonical JSON body, not arbitrary raw JSON formatting:

canonical_body = PHP-compatible canonical_json(request_object)
legacy Sign = md5(base64(canonical_body) + API_KEY)
withdrawal Sign = hmac_sha256(base64(canonical_body) + "." + Timestamp, API_KEY)

Generate one canonical string, sign it, and send it as the request body. Verify client implementations with signature-test-vectors.json. Keep API keys in trusted server-side secrets.

Webhook signing is deliberately different: verify X-Signature as HMAC-SHA256 over the exact raw webhook body before parsing it.

Live Asset Data

See Supported Coins & Networks for the coin/network tables, API identifiers, and guidance on displaying payment options.

Do not copy a static coin/network enum from examples. Use GET /v1/coins-and-fee for discovery and handle validation from the target write endpoint as authoritative. Availability, limits, decimals, fees, rates, and provider-card capability can change.

Response Shapes

Most successful responses use:

{
  "data": {},
  "status": "success"
}

Endpoint errors usually use status and message; validation errors add errors; authentication errors return {"error":"Reason"}. Symbolic error labels in integration code are client-side categories, not guaranteed wire fields.

Idempotency and Retries

The public write API does not accept a general Idempotency-Key header.

• Invoice order_id uniqueness returns 409 and does not replay the original response.
• Withdrawals are not idempotent; timestamp freshness only limits stale replay.
• Static-wallet creation is not idempotent.
• Provider-card creation only reuses an already-active order.
• Withdrawal webhook deliveries currently include a stable X-Idempotency-Key; other webhook families do not guarantee it.

Do not blindly retry a write after an unknown outcome. See Rate Limits and Safe Retries.

Rate-Limit Scope

The published API contract guarantees one specific limit: 100 successful wallet creations per merchant in 60 seconds. Additional limits may apply, so clients must also handle any HTTP 429 response and honor Retry-After when present.