@rail402.dev/agent-helpers

Buyer and agent helpers for Stellar x402. Search the Bazaar and pay for what you find, under a required spend cap.

What you need

Node.js 20+, testnet only. To pay you need a funded Stellar account secret that holds the payment asset with a trustline (fund XLM from friendbot, USDC from the Circle faucet). To only search, omit the secret.

Install

npm install @rail402.dev/agent-helpers

Usage

import { searchBazaar, payAndFetch, discoverAndPay } from "@rail402.dev/agent-helpers";

const config = {
  bazaarUrl: "https://facilitator.rail402.dev", // the Bazaar is served at the facilitator's base URL
  stellarSecret: process.env.RAIL402_SECRET,    // omit for search-only
  network: "stellar:testnet",
};

// Search the Bazaar in natural language.
const found = await searchBazaar(config, "summarize a web page");
if (found.ok) console.log(found.data); // resources with price and input schema

// Pay a known URL, under a cap (atomic units, as a string).
const paid = await payAndFetch(config, "https://api.example.com/summarize", { maxAmount: "100000" });
if (paid.ok) console.log(paid.data.body);

// Discover the cheapest match and pay it, still capped.
const out = await discoverAndPay(config, "summarize a web page", { maxAmount: "100000" });

maxAmount is required. It is atomic units as a string (for example "100000" is 0.01 USDC at 7 decimals). The cap is checked against the actual paid quote, not only the unpaid probe.

stellarSigner takes a pre-built ClientStellarSigner (from @x402/stellar) instead of stellarSecret. It works today for any G... account. It is also the seam for paying from a smart contract account (C...), which becomes a one-liner once @x402/stellar forwards a custom authorization path (x402-foundation/x402#3018) and this package bumps to it. Until then a C... account pays through the direct /verify + /settle path with the helper in examples/smart-account-buyer.

Every call returns a Result, never a thrown string:

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: { code: string; reason: string; retryable: boolean } };

Exports: searchBazaar, payAndFetch, discoverAndPay, plus parseAmount, formatAtomicAmount, readAssetIdentity, readTrustlinePreflight, isPayableResourceUrl.

Part of Rail402. Apache-2.0.