@settlr/sdk

Global payout infrastructure for platforms. Pay anyone, anywhere, with just their email. One API call sends USDC — recipient claims it with any Solana wallet.

🌐 settlr.dev · 📖 Docs · 💻 GitHub

Install

npm install @settlr/sdk

Payout API — Send Money by Email

The core product. Send USDC to anyone with just their email address. No bank details, no forms, no delays.

Quick Start

import { PayoutClient } from "@settlr/sdk";

const payouts = new PayoutClient({ apiKey: "sk_live_xxxxxxxxxxxx" });

// Send a payout — recipient gets an email with a claim link
const payout = await payouts.create({
  email: "[email protected]",
  amount: 250.0,
  memo: "March data labeling — 500 tasks",
});

console.log(payout.id); // "po_abc123"
console.log(payout.status); // "sent"
console.log(payout.claimUrl); // "https://settlr.dev/claim/..."

Batch Payouts

Send up to 500 payouts in a single call:

const batch = await payouts.createBatch([
  { email: "[email protected]", amount: 250.0, memo: "March" },
  { email: "[email protected]", amount: 180.0, memo: "March" },
  { email: "[email protected]", amount: 320.0, memo: "March" },
]);

console.log(batch.total); // 750.00
console.log(batch.count); // 3

Check Status

const payout = await payouts.get("po_abc123");
console.log(payout.status); // "claimed"
console.log(payout.claimedAt); // "2026-02-15T14:30:00Z"
console.log(payout.txSignature); // "5KtP..."

List Payouts

const result = await payouts.list({ status: "claimed", limit: 50 });
result.data.forEach((p) => console.log(p.email, p.amount, p.status));

How It Works

Platform calls POST /api/payouts
        ↓
Recipient gets email with claim link
        ↓
Recipient enters any Solana wallet address
        ↓
USDC transferred on-chain instantly
        ↓
Platform gets webhook with tx signature

Checkout SDK — Accept Inbound Payments

Drop-in React components for accepting USDC payments. Customers pay with email — no wallet setup needed.

BuyButton

import { SettlrProvider, BuyButton } from "@settlr/sdk";

<SettlrProvider
  config={{ apiKey: "sk_live_xxx", merchant: { name: "My Store" } }}
>
  <BuyButton
    amount={49.99}
    memo="Premium Game Bundle"
    onSuccess={(result) => console.log("Paid!", result.signature)}
  >
    Buy Now — $49.99
  </BuyButton>
</SettlrProvider>;

CheckoutWidget

import { CheckoutWidget } from "@settlr/sdk";

<CheckoutWidget
  amount={149.99}
  productName="Annual Subscription"
  productDescription="Full access to all premium features"
  onSuccess={(result) => router.push("/success")}
  theme="dark"
/>;

Checkout Session (Server-Side)

import { Settlr } from "@settlr/sdk";

const settlr = new Settlr({
  apiKey: "sk_live_xxxxxxxxxxxx",
  merchant: { name: "My Store" },
});

const payment = await settlr.createPayment({
  amount: 29.99,
  memo: "Premium subscription",
  successUrl: "https://mystore.com/success",
});

// Redirect to hosted checkout
window.location.href = payment.checkoutUrl;

React Hook

import { SettlrProvider, useSettlr } from "@settlr/sdk";

function CheckoutButton() {
  const { getCheckoutUrl } = useSettlr();
  const url = getCheckoutUrl({ amount: 29.99, memo: "Premium Pack" });
  return <a href={url}>Pay $29.99</a>;
}

Webhooks

Handle payout and payment events:

import { createWebhookHandler } from "@settlr/sdk";

// Next.js App Router
export const POST = createWebhookHandler({
  secret: process.env.SETTLR_WEBHOOK_SECRET!,
  handlers: {
    "payout.claimed": async (event) => {
      console.log("Payout claimed:", event.payment.id);
      await markPaid(event.payment.id);
    },
    "payout.expired": async (event) => {
      await resendPayout(event.payment.id);
    },
    "payment.completed": async (event) => {
      await fulfillOrder(event.payment.orderId);
    },
  },
});

Events

| Event | Description | | ------------------------ | --------------------------------------------- | | payout.created | Payout created, claim email sent | | payout.sent | Email delivered | | payout.claimed | Recipient claimed — USDC transferred on-chain | | payout.expired | Claim link expired (7 days) | | payout.failed | On-chain transfer failed | | payment.created | Checkout payment link created | | payment.completed | Payment confirmed on-chain | | payment.failed | Payment failed | | payment.refunded | Payment refunded | | subscription.created | Subscription started | | subscription.renewed | Subscription charge succeeded | | subscription.cancelled | Subscription cancelled |

Manual Verification

import { verifyWebhookSignature } from "@settlr/sdk";

const isValid = verifyWebhookSignature(body, signature, secret);

Subscriptions

Recurring USDC payments:

import { createSubscriptionClient } from "@settlr/sdk";

const subs = createSubscriptionClient({ apiKey: "sk_live_xxx" });

// Create a plan
const plan = await subs.createPlan({
  name: "Pro",
  amount: 29.99,
  interval: "monthly",
});

// Subscribe a customer
const subscription = await subs.subscribe({
  planId: plan.id,
  customerWallet: "7xKX...",
  customerEmail: "[email protected]",
});

One-Click Payments

Pre-approved spending for returning customers:

import { createOneClickClient } from "@settlr/sdk";

const oneClick = createOneClickClient();

// Customer approves once
await oneClick.approve({
  customerWallet: "...",
  merchantWallet: "...",
  spendingLimit: 100,
});

// Merchant charges later — no popups
const result = await oneClick.charge({
  customerWallet: "...",
  merchantWallet: "...",
  amount: 25,
});

API Keys

| Type | Prefix | Use | | ---- | ---------- | ----------- | | Live | sk_live_ | Production | | Test | sk_test_ | Development |

| Tier | Rate Limit | Fee | | ---------- | ---------- | ---- | | Free | 60/min | 2% | | Pro | 300/min | 1.5% | | Enterprise | 1000/min | 1% |

Get yours at settlr.dev/onboarding.

Multichain Support

Checkout accepts USDC from any major EVM chain — automatically bridged to Solana via Mayan:

| Chain | Bridge Time | Gas Cost | | -------- | ----------- | -------------- | | Solana | Instant | Free (gasless) | | Base | ~1-2 min | ~$0.01 | | Arbitrum | ~1-2 min | ~$0.01 | | Ethereum | ~1-3 min | ~$1-5 |

Full API Reference

PayoutClient

| Method | Description | | ---------------------- | ------------------------- | | create(options) | Send payout by email | | createBatch(payouts) | Batch send (up to 500) | | get(id) | Get payout by ID | | list(options?) | List payouts with filters |

Settlr (Checkout)

| Method | Description | | --------------------------- | ---------------------- | | createPayment(options) | Create payment link | | buildTransaction(options) | Build tx for signing | | pay(options) | Execute direct payment | | getPaymentStatus(sig) | Check payment status | | getMerchantBalance() | Get USDC balance |

Utilities

import { formatUSDC, parseUSDC, shortenAddress } from "@settlr/sdk";

formatUSDC(29990000n); // "29.99"
parseUSDC(29.99); // 29990000n
shortenAddress("ABC...XYZ"); // "ABC...XYZ"

License

MIT