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
What types of applications can be built on the Cryptorefills API?
The API supports any application that needs to deliver digital products paid in crypto. Typical integrations include embedded gift card stores within wallets or exchanges, automated contributor reward systems for DAOs and Web3 platforms, AI agent workflows that purchase products without manual confirmation, and white-label interfaces for regional markets. The fintech and rewards platforms guide covers the business case for several of these patterns with a working code example.
Where do I find my Partner ID to authenticate?
Your Partner ID is on your Cryptorefills account information page. It is passed in the X-Cr-Application header on every request. Country context is passed as a country_code query parameter on the endpoints that accept it. The full authentication header set is documented in Step 1 of the developer reference.
Which payment network should I set as the default?
USDC on Base is the recommended default for most integrations. Base is an Ethereum L2, and transaction fees are consistently low, typically well under $0.05, with confirmation times around 2 seconds. If your user base primarily holds a different asset, the payment methods endpoint returns the full live list of supported coins and networks, including BTC on Lightning, ETH and USDC across Arbitrum, Polygon, and Ethereum mainnet, SOL natively, WLD on WorldChain, and others.
What happens if a user does not send payment within the 30-minute window?
The order expires and the payment address becomes invalid. The user needs to initiate a new order. Because pricing is fetched immediately before order creation, the replacement order generates a fresh rate. Any application that holds a payment address open longer than the 30-minute window will encounter expired order errors on payment confirmation.
Does the API require end-user identity verification?
For standard gift card, eSIM, mobile top-up, and travel purchases, a valid delivery email is the only end-user data required for order fulfillment. eMoney products are subject to identity verification from a defined daily and monthly transaction threshold, as set out in the Cryptorefills terms and conditions. The full delivery and disclosure requirements that apply to integrating partners are in the API overview.