Static Wallets API

Static wallets are reusable cryptocurrency addresses. Create them with the merchant-signed API, then process deposits through signed webhooks.

Create a wallet address

POST /v1/wallet-address

Headers

Name	Required	Description
Content-Type	Yes	application/json
Merchant	Yes	Merchant ID
Sign	Yes	Signature of the canonical request body
Timestamp	No	Unix seconds. If present, Sign must use the timestamped HMAC form.

See Authentication and the executable signature test vectors. The signature is made from PHP-compatible canonical JSON, and those exact canonical bytes must be sent as the HTTP body. Do not sign plain JSON.stringify() or default json.dumps() output.

Request body

Field	Type	Required	Description
network	string	Yes	Network identifier. Input is trimmed and lowercased.
coin	string	Yes	Coin identifier. Input is trimmed and lowercased.
type	string	No	static (default) or merchant.
label	string or null	No	Merchant-defined label, at most 255 characters.
webhook_url	URI or null	No	Address-specific callback URL, at most 255 characters.

{
  "network": "tron",
  "coin": "usdt",
  "type": "static",
  "label": "Checkout deposits",
  "webhook_url": "https:\/\/merchant.example\/coinssend\/webhook"
}

The network/coin example is illustrative. Asset availability can change. Use GET /v1/coins-and-fee for discovery, but treat the create request’s validation response as final because wallet creation may not be available for every listed pair at every moment.

See Supported Coins & Networks for the coin/network tables, API identifiers, and wallet selection guidance.

Multiple static wallets can be created for the same pair. A merchant can have only one merchant wallet for a pair. A merchant wallet deposit is credited without the static-wallet fee or 24-hour hold; those are different product semantics, not an idempotency guarantee.

Success response

{
  "status": "success",
  "data": {
    "address": "TXHXiQ2aXYqtz3y9gEGiVjzxXxXechdLwE",
    "qr_code_url": "https://api.coinssend.com/v1/wallet-addresses/87654321-4321-4321-4321-210987654321/qr"
  }
}

qr_code_url is a public binary-image endpoint. Its path parameter is the wallet-address record ID, not the blockchain address.

Complete server-side examples:

• PHP
• Node.js
• Python

Keep the API key on a trusted server. Browser-side signing exposes the key.

Errors

There is no symbolic code field in the current wire contract. Authentication errors return a simple error string, endpoint errors return status/message, and validation failures return message plus errors.

HTTP status	Current condition	Body shape
400	Missing Merchant or Sign	{"error":"Missing headers"}
400	Duplicate merchant wallet or another request error	{"status":"error","message":"..."}
401	Invalid merchant, signature, or timestamp	{"error":"..."}
403	Merchant status blocks wallet creation	{"status":"error","message":"..."} or authentication error shape
409	Concurrent creation already in progress for the merchant	{"status":"error","message":"Wallet creation already in progress for this merchant."}
422	Invalid fields or unsupported pair	{"message":"...","errors":{"field":["..."]}}
429	Wallet-creation limit reached	{"status":"error","message":"Too many requests. Please try again later."}

The application records at most 100 successful wallet creations per merchant in a 60-second window. Infrastructure in front of the application may enforce additional limits, so clients must also honor 429 and Retry-After when it is present.

Wallet creation has no request idempotency-key contract. A timed-out POST may have succeeded, and retrying a static request can create another address. Do not retry automatically; reconcile the outcome through merchant tooling or support before issuing another creation request.

Current fees and balances

Do not hard-code fee values. Fetch merchant-specific percentages and configured network fees from signed GET /v1/merchants/fees, and use GET /v1/coins-and-fee for the current public asset/fee catalog. Values and enabled pairs can change.

For static wallets, CoinsSend deducts the configured merchant and network fees before crediting the net amount. A static-wallet deposit is held for 24 hours before becoming available. For merchant wallets, those fees are not deducted and the deposit is immediately available. Signed webhook amounts are the authoritative transaction snapshot for your reconciliation record.

Deposit webhook

The public payload event for a successful wallet deposit is wallet.transaction. Use only the event values documented here and in Webhooks.

{
  "event": "wallet.transaction",
  "timestamp": 1746984120,
  "data": {
    "wallet": {
      "address": "TXHXiQ2aXYqtz3y9gEGiVjzxXxXechdLwE",
      "network": "tron",
      "coin": "usdt",
      "label": "Checkout deposits",
      "rate": "1.0001"
    },
    "transaction": {
      "id": "87654321-4321-4321-4321-210987654321",
      "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "block_number": 53214321,
      "amounts": {
        "gross": {"amount": "10.05", "currency": "usd", "crypto": "10.05"},
        "net": {"amount": "9.849", "currency": "usd", "crypto": "9.849"}
      },
      "fees": {
        "merchant": {"amount": "0.201", "currency": "usd", "crypto": "0.201"},
        "network": {"amount": "0", "currency": "usd", "crypto": "0"},
        "total": {"amount": "0.201", "currency": "usd", "crypto": "0.201"}
      },
      "from_address": "TMDKznuDWaZwfZHcM61FYFRx9dAVPndpNv",
      "to_address": "TXHXiQ2aXYqtz3y9gEGiVjzxXxXechdLwE",
      "status": "success",
      "timestamp": 1746984100
    }
  }
}

Callbacks go to the address-specific webhook_url when set, otherwise to the merchant’s default callback URL. Verify X-Signature against the exact raw body bytes before parsing JSON. X-Idempotency-Key is included only when the delivery path supplies one, so consumers should also deduplicate by stable business identifiers such as data.transaction.id.

AML rejection uses the separate external event aml.rejected.static_wallet. See Webhooks for payloads, signature verification, delivery behavior, and the complete event list.