agents-pay

Files (34)

• .gitignore
• SKILL.md
• .gitignore · packages/openclaw/
• PUBLISHING.md · packages/openclaw/
• README.md · packages/openclaw/
• openclaw.plugin.json · packages/openclaw/
• package-lock.json · packages/openclaw/
• package.json · packages/openclaw/
• agentcore_bridge.py · packages/openclaw/runtime/
• stage-skill.mjs · packages/openclaw/scripts/
• SKILL.md · packages/openclaw/skills/agents-pay/
• bridge.ts · packages/openclaw/src/
• config.ts · packages/openclaw/src/
• index.ts · packages/openclaw/src/
• payments.ts · packages/openclaw/src/
• x402.ts · packages/openclaw/src/
• v2-security-contract.json · packages/openclaw/test/fixtures/
• security.test.mjs · packages/openclaw/test/
• test_agentcore_bridge.py · packages/openclaw/test/
• test_setup_openclaw.py · packages/openclaw/test/
• tsconfig.json · packages/openclaw/
• openclaw-setup.md · references/
• operator-guide.md · references/
• security-model.md · references/
• setup.md · references/
• troubleshooting.md · references/
• requirements.txt
• agents_pay_admin.py · scripts/
• test_portability.py · scripts/
• test_resource_resolution.py · scripts/
• test_x402_policy.py · scripts/
• x402_fetch.py · scripts/
• x402_fetch_cli.py · scripts/
• x402_policy.py · scripts/

SKILL.md (first lines)

# 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-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

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws