Payment policy

Robot Pay evaluates both the outgoing request and the payment requirements returned by the service. All core payment dimensions are deny-by-default.

Policy example

const policy = {
  allowedOrigins: ["https://dock.example"],
  allowedPurposes: ["charging", "toll"],
  allowedRecipients: [
    "0x1111111111111111111111111111111111111111"
  ],
  requireIdempotencyKey: true,
  resourceUrlMatch: "origin-and-path",
  paymentRules: [
    {
      id: "arc-usdc",
      network: "eip155:5042002",
      asset: "0x3600000000000000000000000000000000000000",
      maxAmountPerPayment: "500000",
      maxAmountPerWindow: "5000000",
      maxPaymentsPerWindow: 20,
      windowMs: 86_400_000
    }
  ]
} as const;

Request controls

Field	Behavior
`allowedOrigins`	The requested URL origin must be listed. Paths do not belong here.
`allowedPurposes`	`context.purpose` must match an application-defined purpose.
`requireIdempotencyKey`	Defaults to `true`; require an explicit stable key for each logical purchase.
`resourceUrlMatch`	Controls how the URL declared in the `402` must match the requested URL.

resourceUrlMatch defaults to origin-and-path. Use exact when the query string is part of the priced resource, origin only when one origin safely owns all of its paid paths, and none only for an integration with an independently verified binding between requests and quotes.

Payment controls

allowedRecipients is an address allowlist. A payment rule separately binds one network and asset to its maximum amount. Recipient and asset comparisons are case-insensitive; network identifiers are exact.

For every network and asset pair, configure at most one rule.

Field	Required	Meaning
`id`	Yes	Stable identifier included in policy decisions and quotes.
`network`	Yes	CAIP-2 network such as `eip155:5042002`.
`asset`	Yes	Token contract address offered by the service.
`maxAmountPerPayment`	Yes	Maximum atomic amount for one payment.
`maxAmountPerWindow`	No	Maximum aggregate atomic amount during the window.
`maxPaymentsPerWindow`	No	Maximum number of payments during the window.
`windowMs`	With a window limit	Rolling window length in milliseconds.

All amounts must be positive integer strings. Do not use floating-point values for token amounts.

Approval callback

Policy answers whether a quote is mechanically allowed. approvePayment can add a second, application-specific decision before signing:

const robot = createRobotPaymentClient({
  robotId,
  signer,
  policy,
  approvePayment: async (quote) => {
    return fleetControl.approve({
      robotId: quote.robotId,
      purpose: quote.purpose,
      payTo: quote.requirement.payTo,
      amount: quote.requirement.amount,
      asset: quote.requirement.asset
    });
  }
});

Returning false throws a RobotPaymentError with the code approval_denied.

Denials

RobotPaymentPolicyError.decision.violations contains structured violation codes such as origin_not_allowed, recipient_not_allowed, amount_exceeds_limit, budget_exceeded, and duplicate_request. Log the trace ID and violation codes, but avoid logging secrets or full payment headers.

Policy example

Request controls

Payment controls

Approval callback

Denials

On this page