Build a paid request.

Give an API endpoint a USDG price. Confirm the payment before returning the result. Keep that result available through the buyer's saved purchase.

Start with the SDK.

The MIT-licensed paidbeam package provides merchant and buyer entry points. The current prerelease is 0.2.0-rc.1, published on npm. Source and examples are available on GitHub.

npm install paidbeam@0.2.0-rc.1

Before you connect

  1. Get the payment-service URL, merchant credential and registered endpoint ID from your Paidbeam operator.
  2. Configure the endpoint's exact USDG price, receiving wallet and public origin.
  3. Use a connected Robinhood Chain wallet and private, durable purchase storage in your buyer application.

Node.js 24.13+ is the tested server runtime. The buyer entry is browser compatible. Import only paidbeam/buyer in a browser application.

Service access. The SDK is public. A hosted Paidbeam service URL and self-service merchant registration are not available yet. Set up the service with your operator before attempting a real payment.

Protect a merchant route.

Wrap a read-only GET handler with the merchant middleware. The registered endpoint and origin must match the route your buyer requests. Price and recipient come from the authenticated endpoint configuration.

import { protect, PaymentServiceClient } from 'paidbeam/merchant';

const client = new PaymentServiceClient(serviceUrl, merchantKey);

export const GET = protect({
  client,
  endpointId: 'transaction-report',
  publicOrigin: 'https://api.example.com',
}, async request => {
  const report = await generateReport(request);
  return Response.json(report);
});

serviceUrl, merchantKey and generateReport are supplied by your application. Never put the merchant key in browser code.

The handler's successful response is staged before settlement and released after confirmation. A handler can run again after an interrupted preparation, so it must not perform irreversible writes. Use UTF-8 JSON or text responses up to 1,000,000 bytes.

The merchant credential stays on your server. Configure browser CORS explicitly for the buyer's application origin, including payment headers; do not trust an arbitrary forwarded header as your public origin.

Authorize the exact request.

The buyer client verifies the configured merchant origin, USDG asset, amount, recipient and signing domain before asking the wallet to sign. Set an explicit maximum price and the wallet you expect to receive the payment.

import {
  createPaymentClient, robinhoodUsdgPolicy,
} from 'paidbeam/buyer';

const endpoint = 'https://api.paidbeam.xyz/api/transaction-report?hash=' + transactionHash;
const payments = createPaymentClient({
  merchantOrigin: 'https://api.paidbeam.xyz',
  signer, // Your connected wallet
  policy: robinhoodUsdgPolicy({
    payTo: '0x82b7Ed4b9A09eA8F29456A8f18eb4f6d6808cf13',
    maxAmount: 1_000_000n,
  }),
  savePurchase: purchase => privateStore.save(purchase),
});

const result = await payments.purchase(endpoint);
// If pending or interrupted, recover the saved purchase.
const recovered = await payments.recover(savedPurchase);

This example buys a report from Paidbeam. Supply your signer, transactionHash and privateStore. For another merchant, set its endpoint, origin and receiving wallet.

robinhoodUsdgPolicy selects Robinhood Chain mainnet and official Paxos USDG. 1_000_000n is one USDG in atomic units. Your application supplies a signer with an address and signTypedData. The service separately controls activation, gas funding and spending limits.

Signing a valid mainnet authorization can move real USDG once submitted. Check the amount and receiving wallet in your connected wallet. A new call to purchase() can create a new payable order.

Keep the result within reach.

Persist the buyer's purchase record in private, durable storage. The SDK awaits savePurchase before submitting payment authorization. If storage fails, authorization is not submitted.

// Keep the purchase record saved before submission.
const result = await payments.purchase(endpoint);

// Reuse that record if the response is pending or uncertain.
const recovered = await payments.recover(savedPurchase);
const report = await recovered.response.json();

If a response is pending or uncertain, retrieve the same saved purchase and call recover(). It reuses the existing endpoint, order and authorization; it makes no new quote or signature request. Accepted and settled orders can be recovered after the original quote expires.

Keep the endpoint from the saved purchase. If it uses the previous Railway hostname, configure the SDK client with new URL(savedPurchase.endpoint).origin for recovery. The hosted checkout handles either hostname.

Result Next action
200 + payment receipt Read the response and retain the saved purchase.
202 Respect Retry-After, then recover the same record.
503 / PaymentAttemptError Keep the saved record and recover. Inspect the existing order if the result remains uncertain.
409 Ask the merchant or operator to inspect the existing order before attempting another purchase.

A purchase record contains bearer credentials and a signed authorization. Never put it in public URLs, source control or analytics. The SDK has no default localStorage implementation; storage and access control belong to your application.

Read a transaction report.

The first Paidbeam endpoint returns a cached, point-in-time Robinhood Chain transaction report. It includes receipt status, gas usage and fees, block confirmations, and decoded ERC-20 Transfer events. Token amounts remain in atomic units; this report is not a security assessment.

GET https://api.paidbeam.xyz/api/transaction-report?hash=YOUR_32_BYTE_TRANSACTION_HASH

Supply exactly one hash parameter: a 0x-prefixed, 32-byte Robinhood Chain transaction hash. Other query parameters are not accepted. The report costs 1 USDG. You can also buy a report in checkout.

Know the boundaries.

Supported Current boundary
Robinhood Chain mainnet USDG Exact-price EIP-3009 authorization with an explicit recipient and cap.
Read-only GET endpoints JSON/text responses up to 1,000,000 bytes. No streaming or irreversible handler writes.
EOA buyer wallets Contract wallets and delegated accounts are outside this release.
Saved-order recovery Private storage is application supplied. Recovery preserves the existing payment.
x402 v2 payment headers The required order-binding extension must be supported. Generic unmodified x402 clients are not universally compatible.

POST handlers, subscriptions, variable pricing, refunds, batch settlement and multi-host operation are outside the first release. See the public SDK documentation and support issues for integration details.

Explore the SDK