Agents Pay

pay

Let an agent pay for x402-protected content without letting the agent — or anything it reads — decide who gets paid, how much, or how often.

The one idea that matters

A payment decision is made in code, from a policy file, before any signing. Nothing the model says, and nothing inside fetched content, can authorize a payment or raise a limit.

An instruction to a model is not an access control: it is a request that a confused or prompt-injected model may decline. Controls must be enforced in code at the point where payment is authorised.

So in this skill every control is executable, and the model's entire payment surface can only spend an already-approved, bounded session — it can pay, check remaining budget, and obtain an opaque handle for a browser navigation, and nothing more.

When to use

This skill is for an agent that needs to pay for something itself, right now — the coding agent you are talking to, or an agent host like OpenClaw, hitting a paywall mid-task and settling it.

• The agent you are running hits an x402 paywall (HTTP 402) and needs the content
• You need hard spend limits on what that agent can pay, per payment and per session
• A payment was refused and you need to know which rule rejected it

Not this skill: building a payment-capable agent

If you are writing an agent that will take payments or pay on behalf of its own end users — provisioning a wallet per customer, wiring a payments plugin or middleware into a product you are shipping — that is the `agents-build` skill and its references/payments.md. It covers the framework-native integrations and the per-end-user data plane.

The distinction is who spends:

Both are valid; they answer different questions. If you are shipping a payments feature to customers, start with agents-build.

Do NOT use for:

• Non-paid external APIs or tools → agents-connect
• Inbound auth, who may invoke your agent → agents-harden
• Project creation or framework choice → agents-get-started
• Building payment capability into an agent you are shipping → agents-build
• Wallet custody, fiat payouts, or chargeback handling — out of scope

Input

$ARGUMENTS can be:

• A task: setup, wire, debug, session, budget, coinbase, stripe
• A description: "pay for this API", "402 error", "why did it refuse to pay"
• Empty — the skill determines the workflow from context

Read this before deploying

<!-- markdownlint-disable MD036 -->

The agent must not have the ManagementRole, and must not be able to run the admin CLI.

The whole security model rests on that separation. Follow the official IAM roles for AgentCore payments guide:

• A human uses the ManagementRole to create payment instruments and sessions. That role carries an explicit Deny on ProcessPayment.
• The agent runs with the ProcessPaymentRole, which can execute a payment against an already-approved session but cannot create one.

If the agent gets both — or gets shell access to scripts/agents_pay_admin.py while holding the ManagementRole — it can mint itself a fresh budget whenever it exhausts one, and the per-session cap stops bounding anything. AWS says it plainly: "Do not include PaymentSession write permissions ... and ProcessPayment in the same role, or the caller can bypass payment limits by creating new sessions with elevated budgets."

Two mitigations, and you want both:

1. IAM is the real boundary. The runtime role must exclude CreatePaymentSession and every Create* setup action.
2. The admin CLI refuses to run headless as defence in depth — new-session requires a human typing approve at a TTY, and there is no --yes flag. Do not treat this as a substitute for IAM: an agent running as your user in an interactive terminal could still drive it.

Deploy the admin CLI outside the agent's reach where you can — a separate host, or a workstation rather than the runtime image.

Architecture: two paths that never touch

Payments split into an admin path (a human, at a terminal) and a runtime path (the agent). They share resource identifiers and nothing else.

ADMIN PATH — human only, holds credentials
  agentcore add payment-manager / payment-connector   (provider secrets via CLI wizard)
  agents_pay_admin.py init-config                    -> ~/.agents-pay/config.json (0600)
  agents_pay_admin.py new-session                    -> budget-bounded session, typed approval
        |
        |  passes ONLY: PAYMENT_MANAGER_ARN, PAYMENT_INSTRUMENT_ID,
        |               PAYMENT_SESSION_ID, PAYMENT_USER_ID
        v
RUNTIME PATH — spend only; never create
  x402_fetch(url)                        payment_session_status()   [read-only]
        |-- load policy, vet destination      (refuse before any network I/O)
        |-- GET, no redirects, pinned IP, bounded body
        |-- parse 402 challenge strictly
        |-- authorize_payment()               <-- THE decision, in code
        |-- settle, attach proof, discard it  (proof never returned)
        `-- return metadata + body hash; paid body withheld

  prepare_browser_payment(url)           -> opaque single-use handle, no proof
        `-- attach_browser_payment(...)   -> trusted glue only, at navigation

The agent cannot create a session, cannot provision infrastructure, cannot read the policy file's meaning, and never holds a provider credential. When a session budget is spent, spending stops until a human runs new-session again.

Tool inventory

Match by role — your runtime may prefix or rename these.

The split is the design. An agent can spend an approved, bounded session and ask whether it still has budget. It cannot create budget, provision resources, or handle a credential.

Browser / header-only payments

When a paid resource must render in a real browser, the proof has to reach the navigation — but it must not reach the model. Use the handle flow:

# 1. Model-facing tool: pays, returns a handle + redacted receipt (no proof)
result = json.loads(prepare_browser_payment("https://merchant.example/paid"))
# {"paid": true, "handle": "x402h_...", "receipt": {...}}

# 2. Trusted glue redeems the handle and drives the browser
header = attach_browser_payment(result["handle"], "https://merchant.example/paid")
browser.set_extra_http_headers(header)
browser.navigate("https://merchant.example/paid")

Handles are single-use, expire in 90 seconds, and are bound to one origin and path. A handle copied out of a transcript cannot be redeemed for a different resource, cannot be redeemed twice, and is not a credential.

Register prepare_browser_payment as the model's tool. Keep attach_browser_payment in your own glue code — it returns the real header.