API Reference
Complete reference for the ArQPay REST API.
Base URL
https://app.arqpay.com/apiConventions
- Format - JSON request and response bodies.
- Identification - every merchant-scoped request must send the
X-Merchant-IDheader and anOrigin(orReferer) 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 -
quoteDeadlineis Unix seconds; event/log timestamps in responses are ISO-8601 strings.
Endpoint summary
| Area | Endpoints |
|---|---|
| Payments | POST /payments/create, GET /payments/{paymentId}, POST /payments/{paymentId}/confirm, POST /payments/gasless/create, POST /payments/gasless/submit, POST /payments/{paymentId}/confirm-gasless |
| Merchants | GET /merchants/{merchantId}, POST /merchants/{merchantId}/init-auth |
| Chains | GET /chains |
| Wallets | GET /wallets/{address}/tokens, GET /wallets/{address}/tokens-for-amount |
| Tokens | GET /tokens, GET /tokens/price |
| Webhooks | PUT /webhooks/merchants/{merchantId}, GET /webhooks/merchants/{merchantId}, POST /webhooks/test, GET /webhooks/queue/health |
Common headers
| Header | Direction | Description |
|---|---|---|
X-Merchant-ID | request | Your merchant ID. Required on merchant-scoped endpoints. |
Origin / Referer | request | Browser-set (or set manually for server calls). Must be an allowed origin. |
X-RateLimit-Limit / -Remaining / -Reset | response | Rate-limit bookkeeping on limited endpoints. |
X-ArQPay-Signature / -Timestamp / -Event | webhook | Outbound 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:
| Param | Type | Description |
|---|---|---|
chainId | number | Optional. 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:
| Param | Type | Required | Description |
|---|---|---|---|
token | address | yes | Token address. |
chainId | number | yes | Chain the token lives on. |
Response:
json
{ "symbol": "USDC", "chainId": 1, "priceUSD": "1.0001" }