The @coin-voyage/paykit package is the recommended way to integrate CoinVoyage payments into your web application. It provides React context providers that manage wallet connections and order state, a ready-made button component with a built-in payment modal, and a server-side API client that abstracts every authenticated endpoint. You can use as much or as little of the SDK as your integration requires — reach for the UI components for the fastest path to production, or drop down to the ApiClient when you need full control over the payment flow.
Installation
Install the SDK alongside its peer dependency @tanstack/react-query:
What’s in the package
The SDK exports several building blocks. Here is what each one does and when you use it.
PayKitProvider
PayKitProvider is a React context provider that wraps your application and tracks the state of the order flow. It requires your API key and optionally accepts environment, visual mode, custom theme, and wallet callback configuration. Any component tree inside PayKitProvider can render PayButton components and call usePayStatus.
Read the PayKitProvider reference →
WalletProvider
WalletProvider sits outside PayKitProvider and manages wallet connections for EVM, Solana, Sui, and UTXO chains. It accepts a config prop that lets you supply RPC URLs, wallet adapters, and connector settings per chain type. Both providers are required to use the PayButton component.
Read the WalletProvider reference →
PayButton is a pre-styled button that opens a payment modal when clicked. You configure it with the destination chain, token, amount, and address (or a server-generated orderId), and it handles the entire payment UX including wallet selection, transaction signing, and status tracking. A PayButton.Custom variant gives you a render prop pattern to use your own button element while keeping the modal logic.
Read the PayButton reference →
Fiat on-ramp with Stripe Link (gated)
Approved organizations can offer a USD- or EUR-funded on-ramp option inside the same PayKit modal. The option appears alongside the crypto-first paths users already see, such as Pay to Address and Pay with Wallet.
This flow uses Stripe Link and Stripe’s embedded crypto on-ramp. The user authenticates with Link, completes any required identity checks, selects an eligible payment method, and CoinVoyage coordinates the on-ramp session so the order can be funded without the user starting from a pre-funded crypto wallet.
On-ramp access is currently gated. Contact the CoinVoyage team before enabling options.experimentalFeatures.cardPayments; your organization must be approved before the option is shown to users.
ApiClient
ApiClient is a server-side helper imported from @coin-voyage/paykit/server. It wraps CoinVoyage REST endpoints for orders, invoices, quotes, swaps, off-ramp verification, bank accounts, off-ramp intents, webhooks, and more behind a typed interface that returns consistent APIResponse<T> objects. Use it in API routes or server actions for operations that require server-held credentials.
Read the ApiClient reference →
PayKit Headless (Preview)
@coin-voyage/paykit-headless is a separate Preview package for agent and server runtimes that need to satisfy x402 PAYMENT-REQUIRED challenges without browser wallet UI. Use it only for x402 flows; regular checkout and deposit integrations should use @coin-voyage/paykit.
Read the PayKit Headless reference →
usePayStatus
usePayStatus is a React hook that subscribes to real-time status updates for an order from within any component inside PayKitProvider. Use it when you need to react to payment lifecycle changes — for example, to update UI state or trigger server-side fulfillment logic — independently of the PayButton callbacks.
usePayStatus requires both WalletProvider and PayKitProvider to be present in the component tree.
useOrderStatusWS
useOrderStatusWS is a React hook that subscribes to backend order WebSocket events with reconnect handling. Use it for custom payment status panels or dashboard-style views that need live order events outside the default PayButton UI.
Read the useOrderStatusWS reference →
Recommended setup
A typical provider tree looks like this:
Place this Providers component at the root of your application so every page has access to the payment context.