API Reference | CryptPays Developer Documentation

GET/api

API status

Returns a minimal public API status marker.

Request

curl 'https://api.cryptpays.com/api'

HTTP 200

{"status":"OK"}

GET/api/health

Public health check

Basic liveness response. It is not a detailed administrative health report.

Request

curl 'https://api.cryptpays.com/api/health'

HTTP 200

{"status":"ok"}

GET/api/pubkey

Callback verification public key

Retrieves the current PEM public key used to verify callback signatures.

Success: HTTP 200, text/plain

Unavailable: HTTP 503, text/plain

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

Fetch the live key from this endpoint rather than copying a key from documentation. If no key is configured, the response body is Public key not configured.. See Signature Verification.

GET/api/cryptocurrencies

Enabled cryptocurrency catalog

Returns an object keyed by canonical ticker. Only enabled, merchant-usable assets with a safe minimum are included.

Fields for each ticker entry
Field	Type	Meaning
`name`	String	Display name for the asset.
`ticker`	String	Canonical CryptPays ticker.
`minimum`	Decimal string	Current authoritative processing minimum.
`decimals`	Integer	Asset precision.
`type`	String	`native` or `token`.

Example response — live entries and values may differ

{
  "bitcoin_btc": {
    "name": "Bitcoin",
    "ticker": "bitcoin_btc",
    "minimum": "0.00010000",
    "decimals": 8,
    "type": "native"
  },
  "erc20_usdt": {
    "name": "USDT Token",
    "ticker": "erc20_usdt",
    "minimum": "1.250000",
    "decimals": 6,
    "type": "token"
  },
  "sol_sol": {
    "name": "Solana",
    "ticker": "sol_sol",
    "minimum": "0.010000000",
    "decimals": 9,
    "type": "native"
  }
}

GET/api/{ticker}/info

Asset information

Returns current metadata for one enabled canonical asset.

Successful asset info response
Field	Type	Meaning
`ticker`	String	Canonical ticker.
`status`	String	`active` for a usable asset.
`minimum_transaction`	Decimal string	Current authoritative minimum.
`confirmations_required`	Integer	Gateway default confirmation/finality requirement. Solana uses the merchant-facing finality value `1`.
`fee_percent`	Decimal string	Generic/default public fee percentage. The confirmed callback `fee` reports the actual transaction percentage, including any applicable callback-domain tier.

Example response — values may differ

{
  "ticker": "bep20_usdt",
  "status": "active",
  "minimum_transaction": "1.250000000000000000",
  "confirmations_required": 12,
  "fee_percent": "1.00"
}

Unknown tickers return 1101 UNSUPPORTED_CURRENCY; known disabled assets return 1102 CURRENCY_DISABLED.

Payment

Create or reuse a payment address

GET | POST/api/{ticker}/create

Canonical ticker route.

GET | POST/api/{chain}/{token}/create

Separate chain/token route with the same request and response contract.

GET requests use query parameters. POST requests may use form or JSON input. The method used to call this endpoint is independent from callback delivery; post and json control the callback method.

Accepted create parameters
Parameter	Required	Type	Default	Description
`callback_url`	Yes	URL, max 2048	—	HTTPS public callback destination in production and exact payment identity.
`address_out`	Yes	String, max 500	—	Valid merchant payout address for the requested network.
`pending`	No	Integer: 0 or 1	`0`	Enables an informational pending callback.
`confirmations`	No	Integer ≥ 1	Network default	Numeric-chain override within operator limits; does not alter Solana finality.
`post`	No	Integer: 0 or 1	`0`	Selects GET (`0`) or POST (`1`) callback delivery.
`json`	No	Integer: 0 or 1	`0`	With POST, selects form (`0`) or JSON (`1`); GET remains GET.
`priority`	No	String	`default`	`slow`, `default`, or `fast`, subject to network support.
`convert`	No	Integer: 0 or 1	`0`	Requests USDT conversion snapshot fields when a confirmed price exists.

For validation details, transport examples, confirmation behavior, and priority support, see Create Parameters.

HTTP 200 success

{
  "address_in": "0x2222222222222222222222222222222222222222",
  "address_out": "0x1111111111111111111111111111111111111111",
  "callback_url": "https://merchant.example/payments/callback?order_id=123",
  "priority": "default",
  "minimum_transaction_coin": "1.250000000000000000",
  "status": "success"
}

Compatible reuse returns the immutable existing configuration. Cross-family reuse returns 1202 CALLBACK_ADDRESS_FAMILY_CONFLICT. Other common errors are 1001, 1101, 1102, and 1103.

GET/api/{ticker}/logs

Payment and delivery logs

Returns the stored wallet configuration, payment callbacks, and recent delivery attempts for an exact callback URL identity.

Logs request
Parameter	Required	Type	Description
`callback`	Yes	URL, max 2048	Exact callback URL used for payment creation, URL-encoded as the query value.

curl --get 'https://api.cryptpays.com/api/bitcoin_btc/logs' \
  --data-urlencode 'callback=https://merchant.example/payments/callback?order_id=123'

Top-level fields

Logs response envelope
Field	Type	Meaning
`status`	String	`success`.
`address_in`	String	Stored deposit address.
`address_out`	String	Stored merchant payout address.
`callback_url`	String	Stored callback identity.
`notify_pending`	Boolean	Whether pending notifications were enabled.
`notify_confirmations`	Integer	Stored confirmation requirement.
`priority`	String	Stored priority.
`callbacks`	Array	Payment callback lifecycle records.

Callback records

Fields in `callbacks[]`
Field	Type	Meaning
`uuid`	String	Stable lifecycle UUID, identical to the UUID sent in merchant callbacks.
`txid_in`	String or null	Incoming transaction hash. For UTXO deposits this is the bare hash.
`vout`	Integer, conditional	Separate incoming output index for a valid UTXO outpoint.
`txid_out`	String or null	Forwarding transaction identifier.
`value_coin`	Decimal string	Incoming amount for this payment.
`value_forwarded_coin`	Decimal string	Amount forwarded to the merchant.
`confirmations`	Integer	Incoming customer deposit confirmations/finality, not outbound confirmations. Solana is 0 or 1.
`last_update`	Datetime string or null	Last lifecycle update.
`result`	String	Internal lifecycle state: `pending`, `processing`, `sent`, `done`, or `failed`.
`fee_percent`	Decimal string	Actual CryptPays percentage for the payment.
`fee_coin`	Decimal string	Total amount deducted from the incoming payment.
`price`	Decimal string or null	Confirmed USDT price snapshot when available.
`coin`	String	Canonical ticker.
`logs`	Array	Recent callback delivery-attempt records.

Delivery-attempt fields

Fields in `callbacks[].logs[]`
Field	Type	Meaning
`request_url`	String	Callback destination for the attempt.
`responses`	String or null	Recorded merchant response body.
`response_status`	Integer or null	Recorded HTTP status.
`next_try`	Datetime string or null	Scheduled retry time, when applicable.
`pending`	Integer: 0 or 1	Delivery-attempt pending flag, not blockchain finality.
`confirmed`	Integer: 0 or 1	Delivery-attempt success flag, not blockchain finality.

Illustrative Bitcoin logs response

{
  "status": "success",
  "address_in": "bc1qexampledepositaddress0000000000000000000",
  "address_out": "bc1qexamplemerchantaddress000000000000000000",
  "callback_url": "https://merchant.example/payments/callback?order_id=123",
  "notify_pending": false,
  "notify_confirmations": 3,
  "priority": "default",
  "callbacks": [
    {
      "uuid": "9ab63121-41f8-4c56-9c28-c78e9b44b487",
      "txid_in": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "vout": 1,
      "txid_out": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "value_coin": "0.001000000000000000",
      "value_forwarded_coin": "0.000970000000000000",
      "confirmations": 3,
      "last_update": "2026-09-27 12:00:00",
      "result": "done",
      "fee_percent": "1.00",
      "fee_coin": "0.000030000000000000",
      "price": "65000.12000000",
      "coin": "bitcoin_btc",
      "logs": [
        {
          "request_url": "https://merchant.example/payments/callback?order_id=123&uuid=9ab63121-41f8-4c56-9c28-c78e9b44b487",
          "responses": "accepted",
          "response_status": 200,
          "next_try": null,
          "pending": 0,
          "confirmed": 1
        }
      ]
    }
  ]
}

If no matching payment exists, the endpoint returns 1201 PAYMENT_NOT_FOUND.

Errors

Merchant API errors

Merchant API errors use a stable numeric code and English identifier. Validation responses may also include field-level errors.

{
  "status": "error",
  "code": 1001,
  "error": "VALIDATION_FAILED",
  "message": "The request parameters are invalid.",
  "errors": {
    "callback_url": ["The callback URL field is required."]
  }
}

1000–1099 Request and validation1100–1199 Currency and network1200–1299 Payment and address1300–1399 Callback1500–1599 Internal service

Currently defined Merchant API errors
Code	Identifier	HTTP	Meaning	What to do
1001	`VALIDATION_FAILED`	422	One or more request values are invalid.	Correct the fields listed in optional `errors`.
1002	`ENDPOINT_NOT_FOUND`	404	The requested Merchant API route does not exist.	Check the HTTP method and path.
1101	`UNSUPPORTED_CURRENCY`	422	The ticker or network is unknown or unsupported.	Use a canonical ticker from the live catalog.
1102	`CURRENCY_DISABLED`	422	The known asset is currently disabled.	Choose an enabled catalog entry.
1103	`UNSUPPORTED_PRIORITY`	422	The selected network does not support the requested priority.	Use `default` or a supported value.
1201	`PAYMENT_NOT_FOUND`	404	No payment matches the ticker and callback URL.	Verify the canonical ticker and exact stored callback URL.
1202	`CALLBACK_ADDRESS_FAMILY_CONFLICT`	409	The callback URL already belongs to another address family.	Use a new callback URL for the incompatible family.
1501	`INTERNAL_GATEWAY_ERROR`	500	An internal service error occurred.	Retry later; contact support if it persists.