API conventions
Response shape, amounts, safe retries, pagination, timeouts, rate limits, and versioning.
These rules apply to every endpoint.
Responses
Every response has the same shape. A success returns status: true and a data
object. A failure returns status: false with an error string and a code.
{
"status": true,
"data": { }
}Check status first. When it is false, match on code and display error. See
Errors for every code.
Amounts
Send and read amounts as decimal strings, such as "150000". Use a decimal type
for calculations to avoid precision loss.
Idempotency
A create request can time out after Pulse stores the result. The reference lets a
repeated request return that result instead of creating another one.
| Request | reference identifies | A repeat with the same reference |
|---|---|---|
POST /v1/onramp/orders, POST /v1/offramp/orders | One payment in your system. | Returns the existing order. A different body returns 409 duplicate_reference. |
POST /v1/collections | One customer in your system. | Returns the existing collection with the same addresses. Pulse ignores the other fields. |
An order reference must be unique across both order flows.
Store the reference first
Generate the reference in your system. Store it before you send the create request.
Retry the same request
After a timeout, 503 service_unavailable, or 500 internal, send the same body
with the same reference.
Save the ID
After a successful create, store the returned id with your reference. You can
also find an order with GET /v1/orders?reference=..., and a collection with
GET /v1/collections?reference=....
For 409 duplicate_reference, read the existing order. Use a new reference only
when you intend to create a different order.
For 409 quote_changed, refresh the quote again and review the response. Then retry
the order request.
Pagination
GET /v1/orders, GET /v1/collections, and GET /v1/recipients use cursor
pagination. The default page size is 20 and the maximum is 100. If you request more
than 100, Pulse returns 100 records.
Start without a cursor. For each following page, pass the previous response's
meta.next_cursor as cursor. Stop when next_cursor is absent.
Client timeouts
Set finite connection and response timeouts on every API call. A timeout does not confirm failure. See Idempotency before you retry a create request.
Do not poll an order in a tight loop. Increase the interval after each unchanged response, stop at a terminal status, and use webhooks for lifecycle updates.
Rate limits
Keep API traffic below 60 requests per minute for each API key. Poll an individual
order no more than once every five seconds. If the API returns 429 rate_limited,
wait 60 seconds before retrying.
Versioning
Every endpoint path starts with /v1. Keep the base URL and version in configuration
so an environment change does not require code changes.
Pulse records each public API change in the changelog, with any required migration steps.