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.

Files

All paths are inside this skill directory. That is deliberate: some installers copy a single skill folder and flatten it, so a reference to a sibling skill's files (../other-skill/...) can silently break. Everything needed is here.

Process

Step 0: Prerequisites

python3 --version                      # 3.9+
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
agentcore --version

bedrock_agentcore.payments must be importable. Verify: python -c "from bedrock_agentcore.payments import PaymentManager".

Step 1: Provision payment resources — human runs this outside the LLM loop

The agent must NOT run this step; it involves provider credentials. Tell the user to open a separate terminal and complete the commands there. Do not ask them to paste credentials, command output, deployed state, or generated IDs back into chat. Wait only for the user to confirm that setup completed.

npm install -g @aws/agentcore
agentcore add payment-manager          # NO FLAGS — interactive wizard
agentcore add payment-connector        # NO FLAGS — interactive wizard
agentcore deploy                       # interactive deployment

Run both agentcore add commands with no flags to keep the complete setup flow in the human's terminal. In particular, connector secret flags put values in shell history and the process list. See references/setup.md for obtaining Coinbase CDP / Stripe Privy credentials and for the split IAM policies.

agentcore/.env.local holds provider secrets in plaintext until deploy uploads them to AgentCore Identity. Ensure .env.local is gitignored. The agent must never read that file.

Step 2: Write the payment policy — human runs this

Until this file exists, every payment is refused. There is no permissive default.

python3 scripts/agents_pay_admin.py init-config \
  --max-per-payment-usd 0.05 \
  --network eip155:84532 \
  --recipient 0xMerchantWalletAddress

Use repeatable --recipient flags for the normal allowlist mode. To deliberately let publishers choose the beneficiary, use --allow-any-recipient instead. The two modes are mutually exclusive.

Add --origin https://<host> (repeatable) only to pin the agent to a known merchant set; omitted, it may fetch any public HTTPS site.

Written to ~/.agents-pay/config.json, mode 0600, via atomic replace. It pins these policy keys (use hyphens for the corresponding CLI flags, e.g. --allow-any-recipient):

A missing recipient mode denies. Setting both recipient modes is invalid. There is no implicit wildcard. USDC contracts come from a pinned table in the admin script, so a look-alike contract cannot be pasted in.

Step 3: Create a per-user instrument — human runs this

python3 scripts/agents_pay_admin.py create-instrument --email you@example.com

The manager ARN and connector ID are read from agentcore/.cli/deployed-state.json (written by agentcore deploy), so nothing needs copying by hand — run it from the project directory, or pass --manager-arn / --connector-id.

It prints the wallet address, the delegation URL, and the export lines for the runtime. Delegation and funding are then done by the end user — see references/setup.md.

Step 4: Approve a budget-bounded session — human runs this

python3 scripts/agents_pay_admin.py new-session --budget 1.00 --expiry-minutes 60

This prints the parameters and requires typing approve at a TTY. That typed confirmation is the approval artifact — it cannot be produced by the model, by chat history, or by text inside fetched content. There is no --yes flag: the command refuses outright without an interactive terminal, so an agent cannot satisfy the gate even by invoking it directly.

The runtime role must not hold bedrock-agentcore:CreatePaymentSession. Otherwise an agent that exhausts one budget can mint another, and a per-session cap stops being a cumulative bound. See the split policies in references/setup.md.

Step 5: Wire the runtime — human completes this locally

The human exports the identifiers or writes the OpenClaw plugin configuration in the same separate terminal. The agent must not ask the user to paste these values or command output into chat. For OpenClaw, follow references/openclaw-setup.md.

export PAYMENT_MANAGER_ARN=...   PAYMENT_INSTRUMENT_ID=...
export PAYMENT_SESSION_ID=...    PAYMENT_USER_ID=alice
export AWS_REGION=us-west-2
python3 scripts/agents_pay_admin.py preflight

After the user confirms that local wiring is complete, the agent may call only the read-only session-status tool to verify readiness.