npm package: @keychain-pay/onramp
Description: Keychain Onramp SDK - Bank to USDC in minutes
Author: Keychain
Latest version: 1.0.1

# Keychain Onramp SDK

Bank to USDC in minutes. Let your users buy USDC directly from their bank account.

## Features

- **Simple Integration** - Just a few lines of code
- **Bank Linking** - Plaid-powered bank verification
- **Instant Settlement** - Optional instant settlement for amounts ≤$50
- **Same-Day ACH** - Funds settle same business day

## Installation

```bash
npm install keychain-pay/onramp
```

## Quick Start

### 1. Backend: Create a Session

Use your **secret key** (never expose this on the frontend):

```typescript
import { KeychainOnramp } from 'keychain-pay/onramp';

const onramp = new KeychainOnramp('sk_live_xxx');

// Create a session
const session = await onramp.sessions.create({
  destinationAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
  amount: 10000, // $100 in cents (optional)
  successUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel',
  webhookUrl: 'https://yoursite.com/webhooks/keychain',
});

// Return session URL to your frontend
res.json({ url: session.url, sessionId: session.id });
```

### 2. Frontend: Open the Onramp

**Option A: Simple Redirect (no SDK needed)**

```javascript
// Redirect to the onramp
window.location.href = session.url;
```

**Option B: Modal/Popup with Callbacks**

```html
<script src="https://js.trykeychain.com/onramp.js"></script>
<script>
  // Open as modal
  KeychainOnramp.open('sess_xxx', {
    mode: 'modal', // 'redirect' | 'popup' | 'modal'
    onSuccess: (session) => {
      console.log('Success!', session);
    },
    onCancel: () => {
      console.log('User cancelled');
    },
  });
</script>
```

**Option C: React/Next.js**

```tsx
import { open } from 'keychain-pay/onramp/client';

function BuyButton({ sessionId }) {
  return (
    <button onClick={() => open(sessionId, { mode: 'modal' })}>
      Buy USDC
    </button>
  );
}
```

## API Reference

### Backend SDK

#### `KeychainOnramp(secretKey, options?)`

Create a new Onramp client.

```typescript
const onramp = new KeychainOnramp('sk_live_xxx', {
  baseUrl: 'https://developer-api.trykeychain.com', // optional
});
```

#### `onramp.sessions.create(params)`

Create a new onramp session.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `destinationAddress` | string | Yes | Wallet address to receive USDC |
| `destinationChain` | string | No | `'solana'` (default), `'ethereum'`, `'polygon'`, `'base'` |
| `amount` | number | No | Pre-filled amount in cents |
| `successUrl` | string | No | Redirect URL on success |
| `cancelUrl` | string | No | Redirect URL on cancel |
| `webhookUrl` | string | No | Webhook URL for notifications |
| `referenceId` | string | No | Your reference ID |
| `metadata` | object | No | Custom key-value pairs |

Returns:

```typescript
{
  id: 'sess_abc123...',
  url: 'https://checkout.trykeychain.com/buy-usdc?session_id=sess_abc123',
  amount: 10000,
  destinationAddress: '0x...',
  destinationChain: 'solana',
  status: 'pending',
  testMode: false,
  expiresAt: '2024-01-01T00:00:00.000Z',
}
```

#### `onramp.sessions.retrieve(sessionId)`

Retrieve an existing session.

```typescript
const session = await onramp.sessions.retrieve('sess_abc123');
console.log(session.status); // 'pending' | 'completed' | 'expired'
```

### Frontend SDK

#### `KeychainOnramp.open(sessionId, options?)`

Open the onramp flow.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mode` | string | `'redirect'` | `'redirect'`, `'popup'`, or `'modal'` |
| `onSuccess` | function | - | Called on successful completion |
| `onCancel` | function | - | Called when user cancels |
| `onError` | function | - | Called on error |

#### `KeychainOnramp.close()`

Close the modal (if open).

#### `KeychainOnramp.getUrl(sessionId)`

Get the onramp URL for manual navigation.

## Webhooks

When a session completes, we'll send a POST request to your `webhookUrl`:

```json
{
  "type": "onramp.session.completed",
  "id": "evt_xxx",
  "created": "2024-01-01T00:00:00.000Z",
  "data": {
    "session": {
      "id": "sess_xxx",
      "status": "completed",
      "destinationAddress": "0x...",
      "depositedAmount": 10000,
      "instantSettlement": true,
      "transactionHash": "5eykt4...",
      "completedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

## Test Mode

Use test keys (`sk_test_xxx`) during development:

```typescript
const onramp = new KeychainOnramp('sk_test_xxx');
```

Test mode sessions simulate the full flow without real bank transfers.

## Support

- Email: hello@trykeychain.com