Robot Pay SDK
A policy-bound x402 v2 payment client for autonomous machines.
@arcon-network/robot-pay
is the payer SDK for machines that need to purchase digital or physical services
without receiving an open-ended wallet allowance.
It handles exactly one payment challenge and one paid replay per call. The SDK does not store private keys and does not treat a successful payment as permission to operate hardware.
Install
bun add @arcon-network/robot-pay @x402/core @x402/evmUse a signer supported by @x402/evm. The quickstart uses a
Viem account for a compact example.
Request lifecycle
- Validate the requested origin and purpose before contacting the service.
- Send the request with an idempotency key and Arcon trace ID.
- Return immediately when the response is not
402. - Parse x402 v2 payment requirements and match the declared resource URL.
- Select an Exact EVM offer permitted by recipient, network, asset, and budget policy.
- Optionally ask the application's approval callback for authorization.
- Sign the selected payment and replay the request once without following redirects.
- Record a receipt, including ambiguous outcomes that must not be paid again.
Main exports
| Export | Purpose |
|---|---|
createRobotPaymentClient | Creates the recommended Robot Pay client. |
RobotPaymentClient | Class form of the client. |
RobotPaymentPolicyError | Includes structured violations when policy denies a request or quote. |
RobotPaymentError | Reports protocol, approval, configuration, ledger, and ambiguous-outcome failures. |
InMemoryRobotPaymentLedger | Process-local ledger for development and tests. |
evaluateRequestPolicy | Evaluates an origin, purpose, and idempotency context. |
evaluateRequirementPolicy | Evaluates an individual x402 payment requirement. |
validateRobotPaymentPolicy | Validates policy structure before use. |
Result shape
robot.fetch() always returns the service Response when the HTTP exchange
completes. It also reports whether payment was attempted and, for paid requests,
provides the selected quote, local receipt, and decoded facilitator settlement.
const result = await robot.fetch(request);
result.response; // Response
result.paid; // boolean
result.traceId; // arp_...
result.quote; // selected terms when paid
result.receipt; // local payment record when paid
result.settlement; // decoded x402 settlement when supplied by the serviceA receipt may be settled, submitted, rejected, or outcome_unknown.
Treat submitted and outcome_unknown conservatively: investigate or reconcile
them, but do not issue the same logical payment again with a new idempotency key.
Protocol support
This release supports x402 v2 Exact payments on EVM networks. A payment option
must have an eip155: network identifier and match an explicit policy rule.
Continue with policy configuration or the production guide.