/agents-pay

name: agents-pay
description: >
  Use when THIS agent needs to pay for x402-protected content at runtime:
  hitting a paywall mid-task, settling it via AgentCore Payments, and
  applying operator-defined spend limits. Covers payment setup, policy,
  session budgets, and troubleshooting.
  Triggers on: "my agent hit a 402 while calling an API",
  "a tool call returned 402 Payment Required",
  "my agent needs to pay for x402-protected content",
  "let the agent pay for content, capped at $5 per session",
  "set a spend limit for the agent", "ProcessPayment failed",
  or "why did my agent refuse to pay".
  Not for BUILDING payment capability for end users, including wallets
  and framework middleware; use agents-build and references/payments.md.
  For non-paid APIs via Gateway use agents-connect. For inbound auth use
  agents-harden. For project scaffolding use agents-get-started.
allowed-tools: Read Bash
metadata:
  type: skill
  version: "1.0.0"
  author: aws-agentcore

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:

| | `agents-build` → `references/payments.md` | `agents-pay` (this skill) | |---|---|---| | Question | "How do I give the agent I'm building the ability to pay?" | "This agent needs to pay for this thing now" | | When | Build time, in a product you ship | Run time, in the session you are in | | Wallet | One per end user of your product | One for this installation | | Who approves spend | Your product's own flow | The operator, at a terminal |

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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html) 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-bound