> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinvoyage.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CoinVoyage PayKit SDK — overview and installation guide

> Install @coin-voyage/paykit and learn how PayKitProvider, WalletProvider, PayButton, ApiClient, and status hooks fit into your integration.

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`:

<CodeGroup>
  ```bash npm theme={null}
  npm i @coin-voyage/paykit @tanstack/react-query@^5.90.6
  ```

  ```bash pnpm theme={null}
  pnpm add @coin-voyage/paykit @tanstack/react-query@^5.90.6
  ```

  ```bash yarn theme={null}
  yarn add @coin-voyage/paykit @tanstack/react-query@^5.90.6
  ```

  ```bash bun theme={null}
  bun add @coin-voyage/paykit @tanstack/react-query@^5.90.6
  ```
</CodeGroup>

## 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 →](/sdk/paykitprovider)

### 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 →](/sdk/walletprovider)

### 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 `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 →](/sdk/paybutton)

### 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](https://docs.stripe.com/crypto/onramp/embedded-components-integration-guide?platform=web). 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 →](/sdk/apiclient)

### 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 →](/sdk/paykit-headless)

### 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.

<Note>
  `usePayStatus` requires both `WalletProvider` and `PayKitProvider` to be present in the component tree.
</Note>

### 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 →](/sdk/useorderstatusws)

## Recommended setup

A typical provider tree looks like this:

```tsx theme={null}
"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.