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
- Get the payment-service URL, merchant credential and registered endpoint ID from your Paidbeam operator.
- Configure the endpoint's exact USDG price, receiving wallet and public origin.
- 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.
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.
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