@payagentic.ai/sdk

Build AI agents that buy paid API data with programmable stablecoin wallets and spend-policy controls on supported USDC and USDT rails. PayAgentic SDKs connect your server to the gateway; the platform's subscriptions and transaction charges are separate from the SDK's MIT license.

Developer home · Runnable buyer + merchant example · SDK reference · Pricing · Integration support

Start with a working example

Download the local API commerce demo. It includes both sides, installation instructions, expected output and automated tests. Node.js 22+ runs the demo, including for Python and Go developers who want to inspect the HTTP payment exchange. It uses simulated authorization, moves no funds, and does not validate settlement.

For your own integration, use the quickstart, finish asynchronous wallet provisioning, and configure a test API key, gateway URL and wallet ID. The key belongs in your server environment, never browser code. Registered merchant origin and endpoint setup is required to exercise the platform transaction fee flow.

These are pre-1.0 SDKs. A source checkout may be newer than the published package; pin and test a release before upgrading. See the registry's release history for available versions.

Install

Version 0.2.1 fixes the Node.js ESM import failure in 0.2.0. Pin the version below for a reproducible installation. If it is not yet available in the registry, use the source-built package in the downloadable example.

npm install @payagentic.ai/[email protected]
# or
pnpm add @payagentic.ai/[email protected]
yarn add @payagentic.ai/[email protected]
bun add @payagentic.ai/[email protected]

Requires Node.js 22+ (ESM-only, fetch available globally).

Usage

Construct a client

import { PayagenticClient } from "@payagentic.ai/sdk";

const client = new PayagenticClient({
  apiKey: process.env.PAYAGENTIC_API_KEY,
  baseUrl: process.env.PAYAGENTIC_BASE_URL,
  x402WalletId: process.env.PAYAGENTIC_WALLET_ID, // required for x402
});

The client reads PAYAGENTIC_API_KEY, PAYAGENTIC_AGENT_ID, and PAYAGENTIC_BASE_URL from the environment when those options aren't passed explicitly.

Call the gateway

Every endpoint in the gateway's OpenAPI spec is exposed under a per-tag namespace. Method names follow the operationId convention.

// Wallets
const wallets = await client.wallets.listWallets();
const wallet = await client.wallets.getWallet({ path: { id: "wal_…" } });

// Mandates
const mandates = await client.mandates.listMandates();
const coverage = await client.mandates.getMandateCoverage();

x402 paywall walker

The agent kit's x402 namespace wraps fetch so HTTP 402 responses are handled transparently. For a configured paid URL, the walker proposes a payment from your wallet and retries with the rail credential (PAYMENT-SIGNATURE for x402 v2). Confirm gateway transaction status separately; a successful merchant response alone does not prove settlement.

const resourceUrl = process.env.PAYAGENTIC_RESOURCE_URL;
const idempotencyKey = process.env.PAYAGENTIC_IDEMPOTENCY_KEY;
if (!resourceUrl || !idempotencyKey) throw new Error("Set purchase configuration");
const response = await client.x402.fetch(resourceUrl, { maxSpend: "0.01", idempotencyKey });
if (!response.ok) throw new Error("Merchant request failed");

The package includes examples/buy-api.mjs. Set PAYAGENTIC_API_KEY (test key), PAYAGENTIC_BASE_URL, PAYAGENTIC_WALLET_ID, PAYAGENTIC_RESOURCE_URL (registered x402 v2 test endpoint), PAYAGENTIC_MAX_SPEND (decimal string) and PAYAGENTIC_IDEMPOTENCY_KEY in your runtime, then run node node_modules/@payagentic.ai/sdk/examples/buy-api.mjs. Reuse the purchase key only when recovering that same purchase; reconcile an ambiguous result before starting another.

Auto-resume after approval

If a payment is blocked by a policy that requires human approval, opt into auto-resume:

const res = await client.x402.fetch(
  "https://api.vendor.com/paid",
  { waitForApproval: true } // or { timeoutMs: 10 * 60 * 1000 }
);

The SDK subscribes to the gateway's SSE stream, waits for the operator's decision, and either:

• approved → retries the payment and returns the Response
• rejected → throws PolicyDeniedError with the operator's reason
• timeout → throws ApprovalTimeoutError

Without waitForApproval, PendingApprovalError is thrown immediately as before.

Typed errors

Non-2xx responses become typed exceptions you can instanceof-check:

import { PayagenticClient, UnauthorizedError, RateLimitError } from "@payagentic.ai/sdk";

try {
  await client.wallets.listWallets();
} catch (err) {
  if (err instanceof UnauthorizedError) { /* … */ }
  if (err instanceof RateLimitError)     { /* … */ }
}

Full hierarchy: PayagenticError → { Conflict, Forbidden, Internal, Network, NotFound, RateLimit, ServiceUnavailable, Unauthorized, Validation }Error. Use isRetryable(err) for retry classification.

Framework adapters

Tree-shakeable namespace for AI agent frameworks:

import { adapters } from "@payagentic.ai/sdk";

// Anthropic Claude tool use
const tools = adapters.anthropic.toTools(client);

// OpenAI Agents SDK
const openaiTools = adapters.openai.toTools(client);

// LangChain
const langchainTools = adapters.langchain.toTools(client);

// Vercel AI SDK
const aiTools = adapters.vercelAi.toTools(client);

Generated transport

The HTTP transport in src/_generated/ is generated by @hey-api/openapi-ts from the gateway's OpenAPI 3.1 spec at ../../api/openapi.json. It's regenerated by the monorepo's just gen-sdk-ts recipe.

src/_generated/ is marked linguist-generated=true in .gitattributes so GitHub PRs collapse it. Do not edit those files directly — modify the gateway's #[utoipa::path] annotations + regenerate.

Development (from the monorepo)

# Regenerate the transport from api/openapi.json
just gen-sdk-ts

# Per-SDK commands (cd sdks/typescript first)
pnpm typecheck
pnpm test
pnpm build
pnpm lint

Publishing

just release-ts 0.2.1   # bumps version, builds, npm publish, tags

Needs NPM_TOKEN in ~/.npmrc (npm login --scope=@payagentic).

License

MIT