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

npm install keychain-pay/onramp

Quick Start

1. Backend: Create a Session

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

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)

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

Option B: Modal/Popup with Callbacks

<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

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.

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:

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

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:

{
  "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:

const onramp = new KeychainOnramp('sk_test_xxx');

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

Support

• Email: [email protected]