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

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

### ApiClient

`ApiClient` is a server-side helper imported from `@coin-voyage/paykit/server`. It wraps CoinVoyage REST endpoints for creating pay orders, listing orders, fetching quotes, swaps, managing KYC links, bank accounts, withdrawals, 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 →](/v2/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 →](/v2/sdk/paykit-headless)

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

<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 PayOrder 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 →](/v2/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.