How to integrate the Cryptorefills API: a step-by-step walkthrough from authentication to delivery

What the Cryptorefills API covers

The Cryptorefills REST API gives any application access to the same catalog on the platform: 6,600+ gift card brands across 180+ countries, mobile top-ups for 180+ markets, eSIMs for 200+ countries, direct flight booking, and hotel stays. Payment settles in stablecoins or major crypto assets. The order lifecycle runs from catalog discovery through payment address generation to status tracking and product delivery, all through a documented set of endpoints.

The applications built on top of this span a wide range. A consumer fintech product can embed a branded gift card store that settles in USDC. A DAO tooling platform can automate contributor reward distribution triggered by on-chain events. An AI agent can execute purchases via the MCP path without a human approval step. The underlying API sequence is the same in each case; what differs is which parts the application manages directly and which it delegates.

The fintech and rewards platforms guide covers the business case and a working Node.js example. This article covers integration architecture: what the nine endpoints produce, how they depend on each other, and where issues arise in production.

The nine-step Cryptorefills API sequence

Each endpoint produces data the next one requires. Reordering the sequence or skipping a step produces errors that are difficult to reproduce in development and consistent in production.

The full endpoint reference with cURL examples and full response schemas is in the developer documentation. The sections below cover the decisions the reference does not explain.

Cryptorefills API production decisions

Pricing must be fetched immediately before order creation

Crypto exchange rates shift continuously. A price retrieved when a user loads a product page may be materially different from the rate when they confirm the purchase. Passing a stale price to the order creation endpoint produces a mismatch the API will reject. The pricing endpoint is fast enough to call in the same user action that triggers checkout, and that is where it belongs in the request sequence. Architectures that store a quoted price and reuse it later will encounter this class of failure at scale.

Validation is a required step

POST /v5/orders/validations runs a synchronous pre-flight against the order parameters before a payment address is generated. The conditions it catches (real-time availability changes and denomination mismatches that occur between catalog load and order time) are server-side and invisible to the client. An application that skips validation and sends users directly to order creation will produce a category of failures that only surface after a payment address has been issued. The validation request body is identical to the order creation body, so a passing response means the subsequent call reuses the same parameters without modification. See the validation reference for the schema.

Status tracking via SSE requires a server-side proxy

The streaming status path uses Server-Sent Events routed through a server-side proxy to /v5/orders/{orderId}/subscribe. A direct EventSource connection from the browser to the Cryptorefills API fails in most environments due to CORS restrictions. The proxy maintains the persistent connection server-side and forwards events to the client. Implementing exponential backoff on reconnection handles transient failures cleanly. For environments that do not support persistent server-side connections (certain serverless and edge runtimes fall into this category), the polling fallback at GET /v5/orders/{orderId} is the appropriate alternative.

The beneficiary email determines where delivery goes

Cryptorefills delivers the purchased product directly to the email address in the order body. A test or placeholder email means the end user receives nothing. The order will still complete and the API will return no error. The product goes to the wrong address. For integrations where the end user's email is collected at checkout, verify that the application is passing the user's actual address through to the order body. Your UX should also make clear to the end user that the order is fulfilled by Cryptorefills.

REST or MCP: choosing the right path

The REST API suits applications that manage the checkout experience directly: an embedded store within a consumer app, a rewards distribution system triggered by server-side events, or a white-label gift card interface serving a specific regional market. The application owns the full order lifecycle and controls the user experience at each step.

The MCP path exposes the same catalog and order endpoints as tool calls accessible to AI agents. A session with Cryptorefills connected can search the catalog and execute purchases through natural language without a checkout UI. The autonomous variant, which uses the x402 protocol for payment without a human confirmation step, is covered in the AI agents and x402 guide. For individual users rather than developers, the consumer-facing version of the MCP connection is in the Claude and Cryptorefills guide.

The decision between the two paths is architectural and depends on whether checkout is managed programmatically by the application or delegated to an agent runtime. Both paths draw from the same catalog and order infrastructure, and go through the same validation and order creation endpoints.

Frequently asked questions