Skip to content

API Reference ​

Complete reference for the ArQPay REST API.

Base URL ​

https://app.arqpay.com/api

Conventions ​

  • Format - JSON request and response bodies.
  • Identification - every merchant-scoped request must send the X-Merchant-ID header and an Origin (or Referer) that matches one of your merchant's allowed origins. See Authentication.
  • Errors - non-2xx responses use the shape { "error": "<code>", "message": "<detail>" }.
  • Amounts - token amounts are integer strings in the token's smallest unit (wei-like, scaled by decimals). Fiat amounts are decimal strings ("49.99").
  • Addresses & hashes - lowercase-hex 0x… strings. Addresses are 20 bytes (40 hex chars), hashes/IDs are 32 bytes (64 hex chars).
  • Timestamps - quoteDeadline is Unix seconds; event/log timestamps in responses are ISO-8601 strings.

Endpoint summary ​

AreaEndpoints
PaymentsPOST /payments/create, GET /payments/{paymentId}, POST /payments/{paymentId}/confirm, POST /payments/gasless/create, POST /payments/gasless/submit, POST /payments/{paymentId}/confirm-gasless
MerchantsGET /merchants/{merchantId}, POST /merchants/{merchantId}/init-auth
ChainsGET /chains
WalletsGET /wallets/{address}/tokens, GET /wallets/{address}/tokens-for-amount
TokensGET /tokens, GET /tokens/price
WebhooksPUT /webhooks/merchants/{merchantId}, GET /webhooks/merchants/{merchantId}, POST /webhooks/test, GET /webhooks/queue/health

Common headers ​

HeaderDirectionDescription
X-Merchant-IDrequestYour merchant ID. Required on merchant-scoped endpoints.
Origin / RefererrequestBrowser-set (or set manually for server calls). Must be an allowed origin.
X-RateLimit-Limit / -Remaining / -ResetresponseRate-limit bookkeeping on limited endpoints.
X-ArQPay-Signature / -Timestamp / -EventwebhookOutbound webhook delivery metadata.

Rate limits ​

Payment-creation endpoints are limited to 60 requests per minute per merchant. Exceeding the limit yields:

json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 60 per minute",
  "retryAfter": 42
}

with HTTP 429. Honor retryAfter (seconds) before retrying.

Tokens ​

GET /tokens ​

Lists enabled tokens, optionally filtered by chain.

Query parameters:

ParamTypeDescription
chainIdnumberOptional. Restrict to one chain (e.g. 1 for Ethereum).

Response: array of token objects:

json
[
  {
    "id": "1_0xA0b86991c6218b36c1d19D4a2e9Eb0cEf3607e9",
    "name": "USD Coin",
    "symbol": "USDC",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cEf3607e9",
    "decimals": 6,
    "formatDecimals": 2,
    "chainId": 1,
    "permitSupported": true,
    "isStable": true,
    "stablePeg": "USD",
    "enabled": true,
    "featured": true,
    "order": 1
  }
]

permitSupported indicates whether the token can be used for gasless payments.

GET /tokens/price ​

Returns the current USD price of a token.

Query parameters:

ParamTypeRequiredDescription
tokenaddressyesToken address.
chainIdnumberyesChain the token lives on.

Response:

json
{ "symbol": "USDC", "chainId": 1, "priceUSD": "1.0001" }

ArQPay — Crypto payment processing