# SDK Guide

The PayChain SDK is the recommended integration path for Node.js and TypeScript backends. It wraps the same public REST API with typed helpers, safer payout split handling, idempotency support, error mapping, and webhook verification utilities.

{% hint style="info" %}
**Positioning note:** Use the SDK when your backend runs Node.js or TypeScript. Use the REST API directly when you need another language, full HTTP control, or your own internal SDK.
{% endhint %}

### Install

```bash
npm install @paychainhq/sdk
```

### Create a client

```ts
import { PayChain } from '@paychainhq/sdk';

const paychain = new PayChain({
  apiKey: process.env.PAYCHAIN_API_KEY!,
  businessId: process.env.PAYCHAIN_BUSINESS_ID!,
  environment: 'live'
});
```

### What the SDK covers

* Customers.
* Invoices.
* Payout route attachment.
* Dynamic payout recipients.
* Withdrawals.
* Webhooks.
* Balances.
* Transactions.
* Networks.
* Tokens.

### What the SDK does not cover

* Admin APIs.
* Dashboard-session flows.
* Route-template creation, archive, or delete.
* API key creation, rotation, or revocation.
* Billing mutation flows.
* Internal gas sponsorship controls.
* Wallet provider, paymaster, RPC provider, signer, or treasury-private implementation details.

{% hint style="warning" %}
**Security note:** The SDK is server-side only. Do not bundle it into browser or mobile apps with API keys.
{% endhint %}

### Idempotency

Every mutating operation should include an idempotency key.

```ts
await paychain.invoices.create(
  {
    amount: '100.00',
    token: 'USDC',
    chain: 'evm',
    networkId: 'base-mainnet'
  },
  { idempotencyKey: 'order_123_invoice' }
);
```

### Webhook verification

Webhook verification must use the raw request body.

```ts
import { verifyWebhookSignature } from '@paychainhq/sdk';

const verified = verifyWebhookSignature({
  rawBody,
  signature: request.headers['x-webhook-signature'],
  secret: process.env.PAYCHAIN_WEBHOOK_SECRET!
});

if (!verified) {
  throw new Error('Invalid PayChain webhook signature');
}
```

{% hint style="danger" %}
**Raw body note:** Do not parse and re-stringify JSON before verifying. Use the exact bytes PayChain sent.
{% endhint %}

### When to use REST instead

Use REST directly when:

* Your backend is not Node.js or TypeScript.
* You need language-specific HTTP instrumentation.
* You want to build your own wrapper.
* You need to inspect exact request and response payloads.
* You are debugging endpoint-level behavior.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/developer-quickstart/sdk-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.