Skip to main content

Documentation Index

Fetch the complete documentation index at: https://coinvoyage-3c99945b.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 pay 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: 
npm i @coin-voyage/paykit @tanstack/react-query@^5.90.6

​
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 pay order flow. It requires your API key and optionally accepts theme, environment, and 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

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 payId), 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 →

​
ApiClient

ApiClient is a server-side helper imported from @coin-voyage/paykit/server. It wraps every CoinVoyage REST endpoint — creating pay orders, fetching quotes, managing webhooks, and more — behind a typed interface that returns consistent APIResponse<T> objects. Use it in your API routes or server actions to create pay orders securely before passing the resulting payId to the client. Read the ApiClient reference →

​
usePayStatus

usePayStatus is a React hook that subscribes to real-time status updates for a pay 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.
A typical provider tree looks like this: 
"use client";

import { PayKitProvider, WalletProvider } from "@coin-voyage/paykit";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <WalletProvider>
        <PayKitProvider
          apiKey={process.env.NEXT_PUBLIC_COIN_VOYAGE_API_KEY!}
          environment="production"
          mode="light"
        >
          {children}
        </PayKitProvider>
      </WalletProvider>
    </QueryClientProvider>
  );
}
Place this Providers component at the root of your application so every page has access to the payment context.