Settlr SDK - Accept Solana USDC payments with privacy. Email checkout, gasless transactions, FHE-encrypted receipts. Private on-chain, compliant off-chain.
npm install @settlr/sdk


> Accept crypto payments without wallets. Customers pay with email. You get USDC instantly.
š Website: settlr.dev
š Docs: settlr.dev/docs
š® Demo: settlr.dev/demo
š» GitHub: github.com/ABFX15/x402-hack-payment
- ā
No wallet required - Customers pay with just an email
- ā
Zero gas fees - No SOL needed, ever (Kora gasless)
- ā
Pay from any chain - Accept USDC from Ethereum, Base, Arbitrum, Polygon, Optimism (Mayan)
- ā
Instant settlement - USDC direct to your Solana wallet
- ā
One component - Drop-in React
- ā
Privacy-preserving - FHE-encrypted receipts via Inco Lightning
- ā
One-click payments - Returning customers pay instantly ā NEW
- ā
2% flat fee - No hidden costs
Enable frictionless repeat purchases for returning customers:
``typescript
import { createOneClickClient } from "@settlr/sdk";
const oneClick = createOneClickClient("https://settlr.dev");
// Step 1: Customer approves a spending limit (once)
await oneClick.approve({
customerWallet: "Ac52MM...",
merchantWallet: "DjLFeM...",
spendingLimit: 100, // $100 max
expiresInDays: 30,
});
// Step 2: Merchant charges customer later (no popups!)
const result = await oneClick.charge({
customerWallet: "Ac52MM...",
merchantWallet: "DjLFeM...",
amount: 25,
memo: "Premium content",
});
console.log(result.txSignature); // Payment completed instantly!
console.log(result.remainingLimit); // $75 left
`
Use cases:
- Gaming: Buy in-game items without interrupting gameplay
- Subscriptions: Charge monthly without re-authentication
- Microtransactions: Seamless small purchases
Settlr now supports private payment receipts using Inco Lightning's Fully Homomorphic Encryption:
- Private on-chain - Payment amounts are encrypted, competitors can't see your revenue
- Compliant off-chain - Merchants can still decrypt for accounting/tax (CSV export works!)
- Selective disclosure - Only customer + merchant can view the actual amount
- Trustless decryption - Inco covalidator network ensures no single point of trust
`typescript
import {
findPrivateReceiptPda,
buildPrivateReceiptAccounts,
encryptAmount,
PrivacyFeatures,
} from "@settlr/sdk";
// Check privacy capabilities
console.log(PrivacyFeatures);
// {
// ENCRYPTED_AMOUNTS: true,
// ACCESS_CONTROL: true,
// ACCOUNTING_COMPATIBLE: true,
// TRUSTLESS_DECRYPTION: true
// }
// Derive PDA for a private receipt
const [receiptPda] = findPrivateReceiptPda("payment_123");
// Build accounts for issuing private receipt
const accounts = await buildPrivateReceiptAccounts({
paymentId: "payment_123",
amount: 99.99,
customer: customerWallet,
merchant: merchantWallet,
});
`
> Private on-chain. Compliant off-chain. Your competitors can't see your revenue, but your accountant can.
Settlr integrates Range Security to screen wallets before processing payments:
`typescript
import { screenWallet, isWalletBlocked, RiskLevel } from "@settlr/sdk";
// Screen a wallet for sanctions, fraud, mixers, etc.
const result = await screenWallet("SomeWalletAddress...");
if (result.riskLevel === RiskLevel.SEVERE || result.isSanctioned) {
console.log("Wallet is blocked:", result.categories);
// Don't process payment
}
// Quick check
const blocked = await isWalletBlocked("SuspiciousWallet...");
if (blocked) {
return { error: "Payment blocked for compliance" };
}
`
What Range screens for:
- š« Sanctions - OFAC, EU sanctions lists
- šµļø Fraud - Known scam wallets
- š Mixers - Tornado Cash, etc.
- š Darknet - Illicit marketplace activity
- š Ransomware - Known attack wallets
- š° Gambling - Unlicensed gambling (configurable)
Enable ZK-shielded payments for privacy-conscious merchants:
`typescript
import {
createPrivacyCashClient,
shieldPayment,
privateTransfer,
} from "@settlr/sdk";
// Initialize Privacy Cash
const privacy = createPrivacyCashClient({
connection,
wallet,
network: "mainnet-beta",
});
// Shield funds (move to private pool)
const shieldTx = await shieldPayment(privacy, 100); // $100 USDC
console.log("Shielded:", shieldTx);
// Private transfer (ZK-shielded, amount hidden)
const transferTx = await privateTransfer(privacy, "RecipientWallet...", 50);
console.log("Private transfer:", transferTx);
`
Privacy Cash features:
- š ZK-shielded transactions
- šļø Amount hidden from on-chain observers
- ā” Fast finality on Solana
- š° Supports USDC and SOL
`bash`
npm install @settlr/sdk
Sign up at settlr.dev/onboarding to register your business and get an API key. Your wallet address is linked to your API key automatically.
`typescript
import { Settlr } from "@settlr/sdk";
const settlr = new Settlr({
apiKey: "sk_live_xxxxxxxxxxxx", // Your API key from dashboard
merchant: {
name: "My Store",
// walletAddress is optional - automatically fetched from your API key
},
});
const payment = await settlr.createPayment({
amount: 29.99,
memo: "Premium subscription",
});
// Redirect customer to checkout
window.location.href = payment.checkoutUrl;
`
> Note: When you register at settlr.dev/onboarding, your wallet address is linked to your API key. The SDK automatically fetches it - no need to include it in your code!
The easiest way to accept payments - just drop in a button:
`tsx
import { SettlrProvider, BuyButton } from "@settlr/sdk";
function App() {
return (
apiKey: "sk_live_xxxxxxxxxxxx",
merchant: { name: "GameStore" }, // Wallet fetched from API key
}}
>
memo="Premium Game Bundle"
onSuccess={(result) => {
console.log("Payment successful!", result.signature);
unlockContent();
}}
>
Buy Now - $49.99
);
}
`
Full embeddable checkout with product info:
`tsx
import { CheckoutWidget } from "@settlr/sdk";
productName="Annual Subscription"
productDescription="Full access to all premium features"
productImage="/subscription.png"
onSuccess={(result) => router.push("/success")}
onError={(error) => console.error(error)}
/>;
`
Settlr checkout handles authentication via Privy:
- Email login ā Creates embedded Solana wallet automatically
- Wallet login ā Connects Phantom, Solflare, or Backpack
No wallet-adapter setup needed. Just redirect to checkout.
Customers can pay with USDC from any supported chain. Settlr automatically bridges funds to your Solana wallet via Mayan:
| Source Chain | Bridge Time | Gas Cost |
| ------------ | ----------- | -------------- |
| Solana | Instant | Free (gasless) |
| Base | ~1-2 min | ~$0.01 |
| Arbitrum | ~1-2 min | ~$0.01 |
| Optimism | ~1-2 min | ~$0.01 |
| Polygon | ~1-2 min | ~$0.01 |
| Ethereum | ~1-3 min | ~$1-5 |
You only need a Solana wallet - cross-chain bridging is automatic.
`tsx
import { SettlrProvider, useSettlr } from "@settlr/sdk";
function App() {
return (
apiKey: "sk_live_xxxxxxxxxxxx",
merchant: {
name: "My Game",
// walletAddress optional - linked to your API key
},
}}
>
);
}
// In your component
function CheckoutButton() {
const { getCheckoutUrl } = useSettlr();
const handlePay = () => {
const url = getCheckoutUrl({ amount: 29.99, memo: "Premium Pack" });
window.location.href = url;
};
return ;
}
`
Generate shareable payment links programmatically:
`tsx
import { useSettlr } from "@settlr/sdk";
function InvoicePage() {
const { getCheckoutUrl } = useSettlr();
const link = getCheckoutUrl({
amount: 500,
memo: "Invoice #1234",
orderId: "inv_1234",
});
// ā https://settlr.app/checkout?amount=500&merchant=My+Game&...
}
`
Drop-in payment button component.
`tsx`
memo="Order description" // Optional
orderId="order_123" // Optional: your order ID
onSuccess={(result) => {}} // Called on successful payment
onError={(error) => {}} // Called on payment failure
onProcessing={() => {}} // Called when payment starts
useRedirect={false} // Use redirect flow instead of direct payment
successUrl="https://..." // Redirect URL (if useRedirect=true)
cancelUrl="https://..." // Cancel URL (if useRedirect=true)
variant="primary" // "primary" | "secondary" | "outline"
size="md" // "sm" | "md" | "lg"
disabled={false}
className=""
style={{}}
>
Buy Now - $49.99
Full checkout UI component with product info.
`tsx`
productName="Annual Subscription" // Required
productDescription="Description" // Optional
productImage="/image.png" // Optional
merchantName="My Store" // Optional (uses config)
memo="Transaction memo" // Optional
orderId="order_123" // Optional
onSuccess={(result) => {}} // Called on success
onError={(error) => {}} // Called on error
onCancel={() => {}} // Called on cancel
theme="dark" // "dark" | "light"
showBranding={true} // Show "Powered by Settlr"
className=""
style={{}}
/>
| Key Type | Prefix | Use Case |
| -------- | ---------- | ----------------------------------- |
| Live | sk_live_ | Production payments |sk_test_
| Test | | Development/testing (no validation) |
| Tier | Requests/min | Platform Fee |
| ---------- | ------------ | ------------ |
| Free | 60 | 2% |
| Pro | 300 | 1.5% |
| Enterprise | 1000 | 1% |
1. Go to settlr.app/dashboard
2. Connect your wallet
3. Click "Create API Key"
4. Save the key securely (only shown once!)
Main client class.
#### Constructor Options
`typescript`
interface SettlrConfig {
apiKey: string; // Required: your API key from dashboard
merchant: {
name: string;
walletAddress?: string; // Optional: auto-fetched from API key
logoUrl?: string;
webhookUrl?: string;
};
network?: "devnet" | "mainnet-beta"; // default: 'devnet'
rpcEndpoint?: string;
testMode?: boolean;
}
> Tip: When you register at settlr.dev/onboarding, your wallet address is linked to your API key. You don't need to specify it in the config!
#### Methods
##### createPayment(options)
Create a payment link.
`typescript
const payment = await settlr.createPayment({
amount: 29.99, // Required: amount in USDC
memo: 'Order #123', // Optional: description
orderId: 'order_123', // Optional: your order ID
successUrl: 'https://...', // Optional: redirect after success
cancelUrl: 'https://...', // Optional: redirect on cancel
expiresIn: 3600, // Optional: expiry in seconds (default: 1 hour)
});
// Returns
{
id: 'pay_abc123',
amount: 29.99,
status: 'pending',
checkoutUrl: 'https://settlr.app/checkout?...',
qrCode: 'data:image/svg+xml,...',
createdAt: Date,
expiresAt: Date,
}
`
##### buildTransaction(options)
Build a transaction for signing.
`typescript
const tx = await settlr.buildTransaction({
payerPublicKey: wallet.publicKey,
amount: 29.99,
memo: "Order #123",
});
// Sign and send
const signature = await wallet.sendTransaction(tx, connection);
`
##### pay(options)
Execute a direct payment.
`typescript
const result = await settlr.pay({
wallet: {
publicKey: wallet.publicKey,
signTransaction: wallet.signTransaction,
},
amount: 29.99,
memo: 'Order #123',
});
// Returns
{
success: true,
signature: '5KtP...',
amount: 29.99,
merchantAddress: '...',
}
`
##### getPaymentStatus(signature)
Check payment status.
`typescript`
const status = await settlr.getPaymentStatus("5KtP...");
// Returns: 'pending' | 'completed' | 'failed'
##### createCheckoutSession(options) ā NEW
Create a hosted checkout session (like Stripe Checkout).
`typescript
const session = await settlr.createCheckoutSession({
amount: 29.99,
description: 'Premium Plan',
successUrl: 'https://mystore.com/success?session_id={CHECKOUT_SESSION_ID}',
cancelUrl: 'https://mystore.com/cancel',
webhookUrl: 'https://mystore.com/api/webhooks/settlr', // Optional
metadata: { orderId: 'order_123' }, // Optional
});
// Redirect to hosted checkout
window.location.href = session.url;
// Returns
{
id: 'cs_abc123...',
url: 'https://settlr.app/checkout/cs_abc123...',
expiresAt: 1702659600000, // 30 min expiry
}
`
Get notified when payments complete to fulfill orders automatically.
`typescript
// app/api/webhooks/settlr/route.ts
import { createWebhookHandler } from "@settlr/sdk";
export const POST = createWebhookHandler({
secret: process.env.SETTLR_WEBHOOK_SECRET!,
handlers: {
"payment.completed": async (event) => {
console.log("Payment completed!", event.payment.id);
await fulfillOrder(event.payment.orderId);
await sendConfirmationEmail(event.payment);
},
"payment.failed": async (event) => {
await notifyCustomer(event.payment.orderId);
},
},
});
`
`typescript
import express from "express";
import { createWebhookHandler } from "@settlr/sdk";
const app = express();
app.post(
"/webhooks/settlr",
express.raw({ type: "application/json" }),
createWebhookHandler({
secret: process.env.SETTLR_WEBHOOK_SECRET!,
handlers: {
"payment.completed": async (event) => {
await fulfillOrder(event.payment.orderId);
},
},
}),
);
`
`typescript
import { verifyWebhookSignature, parseWebhookPayload } from "@settlr/sdk";
export async function POST(request: Request) {
const signature = request.headers.get("x-settlr-signature")!;
const body = await request.text();
// Verify signature
if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET!)) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(body);
if (event.type === "payment.completed") {
await fulfillOrder(event.payment.orderId);
}
return new Response("OK", { status: 200 });
}
`
| Event | Description |
| ------------------------ | -------------------------- |
| payment.created | Payment link was created |payment.completed
| | Payment confirmed on-chain |payment.failed
| | Payment failed |payment.expired
| | Payment link expired |payment.refunded
| | Payment was refunded |subscription.created
| | Subscription was created |subscription.renewed
| | Subscription was renewed |subscription.cancelled
| | Subscription was cancelled |subscription.expired
| | Subscription expired |
`json`
{
"id": "evt_abc123",
"type": "payment.completed",
"payment": {
"id": "pay_xyz789",
"amount": 29.99,
"status": "completed",
"orderId": "order_123",
"memo": "Premium subscription",
"txSignature": "5KtP...",
"payerAddress": "7xKX...3mPq",
"merchantAddress": "4dGo...7Ywd"
},
"timestamp": "2025-12-17T10:30:00.000Z",
"signature": "hmac_sha256_signature"
}
##### getMerchantBalance()
Get merchant's USDC balance.
`typescriptBalance: $${balance} USDC
const balance = await settlr.getMerchantBalance();
console.log();`
`typescript
import { formatUSDC, parseUSDC, shortenAddress } from "@settlr/sdk";
formatUSDC(29990000n); // "29.99"
parseUSDC(29.99); // 29990000n
shortenAddress("ABC...XYZ"); // "ABC...XYZ"
`
| Network | USDC Mint | USDT Mint |
| ------- | ---------------------------------------------- | ---------------------------------------------- |
| Devnet | 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU | EJwZgeZrdC8TXTQbQBoL6bfuAnFUUy1PVCMB4DYPzVaS |EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
| Mainnet | | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB |
`typescript
import { SUPPORTED_TOKENS, getTokenMint, getTokenDecimals } from "@settlr/sdk";
// Get token info
const usdcMint = getTokenMint("USDC", "mainnet-beta");
const usdtMint = getTokenMint("USDT", "mainnet-beta");
const decimals = getTokenDecimals("USDC"); // 6
``
MIT