Buyer core

The buyer core discovers gateway resources and pays for them within spending limits you set. The Python and TypeScript implementations both pass the conformance suite and check those limits before signing a payment.

The core talks to the gateway only through its public HTTP contract: GET /api/resources, POST /api/resources/{id}/invoke and the x402 v2 headers PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE. Merchants need no gateway changes to support these clients.

Framework packages map resources to tools and approval settings; the core handles payments.

#Install

pip install agent-commerce-client

npm install @devlab.group/agent-commerce-client viem

#Quick start

import os

from agent_commerce_client import AgentCommerceClient, AgentCommerceError
from eth_account import Account

client = AgentCommerceClient(
    gateway_url="https://merchant.example.com",
    signer=Account.from_key(os.environ["BUYER_PRIVATE_KEY"]),
    networks=["eip155:84532"],  # Base Sepolia
    max_per_call="0.05",  # USDC
    max_per_day="1.00",  # USDC per UTC day
)

for tool in client.list_tools():
    print(tool.name, "-", tool.description)

try:
    result = client.invoke("report", {})
    print(result.status, result.body, result.payment)  # payment: network, transaction hash, payer
except AgentCommerceError as error:
    print(error.code, error.message, error.status)

import { privateKeyToAccount } from 'viem/accounts';
import { AgentCommerceError, createAgentCommerceClient } from '@devlab.group/agent-commerce-client';

const client = createAgentCommerceClient({
  gatewayUrl: 'https://merchant.example.com',
  wallet: privateKeyToAccount(process.env.BUYER_PRIVATE_KEY as `0x${string}`),
  networks: ['eip155:84532'],
  limits: { maxPerCall: '0.05', maxPerDay: '1.00' },
});

for (const tool of await client.listTools()) {
  console.log(`${tool.name}: ${tool.description}`);
}

try {
  const { status, body, payment } = await client.invoke('report', {});
  console.log(status, body, payment?.transaction);
} catch (error) {
  if (!(error instanceof AgentCommerceError)) throw error;
  console.error(error.code, error.status, error.message);
}

Read BUYER_PRIVATE_KEY in your application, create an account object, and pass that object to the client. Raw private keys are refused. Use a dedicated wallet funded to just above the daily limit.

#Configuration

Limits are non-negative decimal strings with up to 6 decimal places. Payments use each network's USDC, with any asset allowed on local Anvil:

Mainnet networks require allow_mainnet=True in Python or allowMainnet: true in TypeScript. Unknown network ids are rejected even with that setting. Invalid configuration fails during client construction. An empty resources list excludes every resource; omit it to include all eligible ones.

By default, each client keeps its daily total in memory, so restarting resets it. To retain the total across restarts or share it across processes, pass a spend store with an atomic add(day, amount) method. It adds USDC base units to the given UTC day's total and returns the new total; negative amounts roll back a reservation.

#Discovery

The core reads GET /api/resources and keeps resources that meet these conditions:

• exposedVia includes http;
• pricing.type is free, or paymentMethods includes x402;
• the resources allowlist is absent or lists its id.

Resources excluded by these checks produce a warning. Eligible resources become tool descriptions:

• name: the resource id;
• description: description, falling back to name, then id; a full stop is added unless the text ends with ., ! or ?, followed by a space and Costs <amount> <currency> per call., Free., or Paid. when the price has no fixed amount;
• inputSchema: inputSchema, or {"type": "object", "properties": {}};
• paid: true unless pricing.type is free;
• needsApproval: paid under approval: paid, always true under always, always false under never.

#Invocation and spending limits

An invocation sends the tool input as the JSON body of POST /api/resources/{id}/invoke. A free resource returns its result directly. A paid resource returns 402 with an x402 challenge. The core uses the official x402 client (@x402/fetch and @x402/evm for TypeScript, or the Python x402 package) to handle the payment:

1. Filter the offers

   An offer is acceptable only with the exact scheme, a network listed in networks, that network's USDC and the EIP-3009 transfer method (extra.assetTransferMethod absent or eip3009; Permit2 would need a prior on-chain approval). The core removes unacceptable offers before the x402 client selects one. It signs nothing if no offer qualifies.

2. Check and reserve before signing

   The x402 before-payment hook checks the selected offer's network, scheme, asset and transfer method again. Its amount, in USDC base units (6 decimals), must fit both the per-call limit and the remaining daily allowance. The hook atomically reserves that amount in the spend store before signing. A rejected offer is never signed.

3. Send once

   The core sends the signed request once, without retrying after any outcome. The default HTTP transport disables retries, and invocation requests do not follow redirects. Each invocation can produce at most one payment.

4. Keep the reservation

   After signing, the reserved amount stays in the daily total even if the gateway rejects the payment, because the core cannot always tell whether funds moved.

The model calling the tool cannot change any limit.

A 2xx response returns { status, body, payment }: the HTTP status, the body and the decoded PAYMENT-RESPONSE header. The body is parsed as JSON when its Content-Type contains json and parsing succeeds; otherwise it stays text. payment carries the network, transaction hash and payer, or is null when the response has no valid payment header, as with a free call.

#Errors

Runtime failures raise AgentCommerceError. Its short message starts with the code and omits keys, headers and backend bodies, so frameworks can show it to the model. For example: LIMIT_EXCEEDED: Price is above the per-call limit.

#Not supported

The core supports x402 exact on EVM. It does not support MPP, Solana or NEAR, the MCP transport, resources requiring AP2 mandates or other authorization, or wallet key storage.

Based on: docs/buyer-core.md