SDK Usage

The simplest way to integrate with the Facora is through our SDK.

Installation

// The SDK is included in this repo under /sdk
import { payAndRequest } from "@facora/sdk";

// Or install from npm (coming soon)
// npm install @facora/sdk

Basic Usage

import { payAndRequest } from "@facora/sdk";

const result = await payAndRequest({
  resourceUrl: "http://localhost:3000/api/alpha-feed"
});

console.log(result.data.alpha);           // unlocked API response
console.log(result.settlement.txHash);    // on-chain settlement proof
console.log(result.settlement.blockNumber);
console.log(result.settlement.facilitator);

Return Shape

{
  data: {
    alpha: string; // your protected response body
  },
  settlement: {
    txHash: string;
    blockNumber: number;
    facilitator: string;
    amount: string;      // "1.00 USDx"
    proofHeader: string; // what gets sent as x-paid-proof
  }
}

How it works: The SDK handles 402 negotiation, picks a facilitator, submits the EIP-2612 permit for USDx, waits for on-chain settlement, and retries your endpoint with x-paid-proof. The caller never needs BNB for gas.

Why this matters

Today, x402 flows trust one facilitator. If that server goes down or censors you, you're dead. We're turning it into a network of facilitators on BNB instead of a single chokepoint. Alpha is live now. Beta/Gamma are next and will be staked & slashable.

Quick Start

Install the SDK and start accepting payments in under 5 minutes.

npm install @facora/sdk

// Or copy the SDK directly
import { payAndRequest } from "@/lib/sdk/payAndRequest"

Environment Variables

NEXT_PUBLIC_USDX_TOKEN_ADDRESS

USDx token contract address on BNB testnet

MERCHANT_WALLET_ADDRESSYour wallet address

Where you receive USDx payments

API Endpoints

GET /api/secret

Returns 402 Payment Required with payment info

// Response (402)
{
  "price": "1 USDx",
  "asset": "0xcfFA309a5Fb3ac7419eBC8Ba4a6063Ff2a7585F5",
  "facilitators": [
    {
      "name": "Alpha",
      "fee": "0.5%",
      "endpoint": "/api/facilitators/alpha",
      "address": "0x1437...",
      "live": true
    }
  ]
}

POST /api/facilitators/alpha

Settle payment through Alpha facilitator

// Request
{
  "permit": "user-signature",
  "amount": "1 USDx"
}

// Response (200)
{
  "paid": true,
  "facilitator": "Alpha",
  "txHash": "0x83fe...",
  "blockNumber": 12345,
  "balanceBefore": "100.00",
  "balanceAfter": "99.00"
}

TypeScript Types

interface PaymentRequiredResponse {
  price: string
  asset: string
  facilitators: Facilitator[]
}

interface SettlementResponse {
  paid: boolean
  facilitator: string
  txHash: string
  blockNumber: number
  balanceBefore: string
  balanceAfter: string
}

Error Handling

try {
  const result = await payAndRequest({
    resourceUrl: "/api/secret"
  })
} catch (error) {
  if (error.message.includes("Insufficient")) {
    // Facilitator needs funding
  } else if (error.message.includes("settlement failed")) {
    // On-chain transaction failed
  }
}

Live Proof (BNB Testnet)

All settlements are verifiable on-chain. Here are the live addresses and an example transaction:

USDx Token Contract
0xcfFA309a5Fb3ac7419eBC8Ba4a6063Ff2a7585F5BscScan
Facilitator Alpha Address
0x1437fE0f155b910dda7A80c64b57C1460793641F
Merchant Address
0x183052a3526d2ebd0f8dd7a90bed2943e0126795
Key Point

Caller paid 0 gas. The facilitator covered all gas costs in BNB. The caller only signed a permit off-chain. This enables AI agents and APIs to buy data/tools without holding BNB for gas.

Try Live Demo

Next Steps