diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 6ce0c35f..091e8d53 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -111,6 +111,18 @@ "authentication": "ON_INSTALL" }, "category": "AI" + }, + { + "name": "aws-agent-payments", + "source": { + "source": "local", + "path": "./plugins/aws-agent-payments" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Payments" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 76bee095..96004052 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -243,6 +243,28 @@ "generative-ai" ], "version": "1.2.1" + }, + { + "category": "payments", + "description": "Enable stateful autonomous agents to pay for x402-paywalled APIs, MCP tools, and web content via microtransactions using AWS AgentCore Payments.", + "keywords": [ + "aws", + "payments", + "x402", + "agentcore", + "micropayments", + "usdc", + "autonomous-agents" + ], + "name": "aws-agent-payments", + "source": "./plugins/aws-agent-payments", + "tags": [ + "aws", + "payments", + "x402", + "agentcore" + ], + "version": "1.0.0" } ] } diff --git a/plugins/aws-agent-payments/.claude-plugin/plugin.json b/plugins/aws-agent-payments/.claude-plugin/plugin.json new file mode 100644 index 00000000..4e07371a --- /dev/null +++ b/plugins/aws-agent-payments/.claude-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "author": { + "name": "Amazon Web Services" + }, + "description": "Enable stateful autonomous agents to pay for x402-paywalled APIs, MCP tools, and web content via microtransactions using AWS AgentCore Payments. Supports Coinbase CDP and Stripe/Privy wallet providers.", + "homepage": "https://github.com/awslabs/agent-plugins", + "keywords": [ + "aws", + "payments", + "x402", + "agentcore", + "bedrock-agentcore", + "micropayments", + "usdc", + "crypto", + "paywall", + "coinbase", + "stripe", + "privy", + "base", + "web3", + "autonomous-agents" + ], + "license": "Apache-2.0", + "name": "aws-agent-payments", + "repository": "https://github.com/awslabs/agent-plugins", + "version": "1.0.0" +} diff --git a/plugins/aws-agent-payments/.codex-plugin/plugin.json b/plugins/aws-agent-payments/.codex-plugin/plugin.json new file mode 100644 index 00000000..48c87915 --- /dev/null +++ b/plugins/aws-agent-payments/.codex-plugin/plugin.json @@ -0,0 +1,43 @@ +{ + "name": "aws-agent-payments", + "version": "1.0.0", + "description": "Enable stateful autonomous agents to pay for x402-paywalled APIs, MCP tools, and web content via microtransactions using AWS AgentCore Payments. Supports Coinbase CDP and Stripe/Privy wallet providers.", + "author": { + "name": "Amazon Web Services", + "email": "aws-agent-plugins@amazon.com", + "url": "https://github.com/awslabs/agent-plugins" + }, + "homepage": "https://github.com/awslabs/agent-plugins", + "repository": "https://github.com/awslabs/agent-plugins", + "license": "Apache-2.0", + "keywords": [ + "aws", + "payments", + "x402", + "agentcore", + "micropayments", + "usdc", + "autonomous-agents" + ], + "skills": "./skills/", + "interface": { + "displayName": "AWS Agent Payments (x402)", + "shortDescription": "Pay for x402-paywalled APIs and content via AgentCore Payments.", + "longDescription": "Enable agents to transparently pay for x402-paywalled APIs, MCP tools, and web content via microtransactions using AWS AgentCore Payments.", + "defaultPrompt": [ + "Pay for this x402-paywalled URL.", + "Set up x402 payments with my Coinbase CDP credentials.", + "Check my payment session status." + ], + "developerName": "Amazon Web Services", + "category": "Payments", + "capabilities": [ + "Read", + "Write" + ], + "websiteURL": "https://github.com/awslabs/agent-plugins", + "privacyPolicyURL": "https://aws.amazon.com/privacy/", + "termsOfServiceURL": "https://aws.amazon.com/service-terms/", + "brandColor": "#FF9900" + } +} diff --git a/plugins/aws-agent-payments/README.md b/plugins/aws-agent-payments/README.md new file mode 100644 index 00000000..c49811d3 --- /dev/null +++ b/plugins/aws-agent-payments/README.md @@ -0,0 +1,82 @@ +# Agent Payments (x402) + +> 🚧 **Preview:** AWS AgentCore Payments is currently in **preview**. APIs, pricing, and availability may change. See [AgentCore Payments documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html) for the latest status. + +Enable stateful autonomous agents to pay for x402-paywalled APIs, MCP tools, and web content via microtransactions using [AWS AgentCore Payments](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html). + +## Overview + +When an AI agent encounters an HTTP 402 (Payment Required) response from an x402-protected endpoint, this skill guides the agent through the payment flow — detecting the challenge, processing payment via AgentCore, and replaying the request with a valid payment header. The agent receives the content without needing to understand the underlying crypto mechanics. + +Works with stateful autonomous agents (OpenClaw, custom AgentCore deployments) and AI coding agents that need to access paid APIs or content. + +Supports **Coinbase CDP** and **Stripe/Privy** wallet providers on **Base Sepolia** (testnet) and **Base Mainnet** networks. + +## Skills + +| Skill | When to use | References | +| --------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `x402-payments` | "pay for this URL", "x402 paywall", HTTP 402 detected, "set up payments" | [protocol](skills/x402-payments/references/protocol.md), [setup](skills/x402-payments/references/setup.md), [debugging](skills/x402-payments/references/debugging.md) | + +## How x402 Payment Works + +```text +Agent request → HTTP 402 + x402 challenge + → AgentCore ProcessPayment (signs tx) + → Replay request with X-PAYMENT header + → HTTP 200 + paid content returned to agent +``` + +## Installation + +### Claude Code + +```bash +/plugin marketplace add awslabs/agent-plugins +/plugin install aws-agent-payments@agent-plugins-for-aws +``` + +### Codex + +```bash +codex plugin marketplace add awslabs/agent-plugins +``` + +Then install **aws-agent-payments** from the Plugins panel. + +## Prerequisites + +- AWS account with [AgentCore Payments](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html) access +- AWS CLI with configured credentials (`aws sts get-caller-identity`) +- IAM role with `bedrock-agentcore.amazonaws.com` trust policy +- Wallet provider account: + - **Coinbase CDP**: API key from [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com) + - **Stripe/Privy**: App credentials from [dashboard.privy.io](https://dashboard.privy.io) +- USDC funding on the target network (Base Sepolia for testnet) + +## Security & Spending Controls + +- **Session spend caps** — each session locks a maximum USDC amount (default $5) +- **Session TTL** — sessions auto-expire (default 4 hours, max 8 hours) +- **Per-request limits** — AgentCore enforces per-transaction caps from the x402 challenge +- **IAM policies** — scope agent permissions to only `ProcessPayment`, `GetPaymentSession` +- **Audit trail** — all payments logged via CloudTrail + +## Supported Networks + +| Network | Chain ID | Use Case | +| ------------ | -------------- | --------------------- | +| Base Sepolia | `eip155:84532` | Testnet / development | +| Base Mainnet | `eip155:8453` | Production | + +## Examples + +- "Pay for this API endpoint: `https://x402-test.example.com/api/weather`" +- "Set up x402 payments with my Coinbase CDP credentials" +- "Check my payment session balance" +- "Create a new payment session with $10 cap" +- "This URL returned a 402, can you pay for it?" + +## Runtime Plugin (Future) + +A TypeScript reference implementation for stateful agent hosts (OpenClaw, etc.) that registers executable tools directly into the agent's tool system is available at [wirjo/agent-toolkit-for-aws](https://github.com/wirjo/agent-toolkit-for-aws/pull/1). This enables fully autonomous payment flows without human-in-the-loop for each transaction. An RFC for the runtime-plugin pattern will be opened separately. diff --git a/plugins/aws-agent-payments/skills/x402-payments/SKILL.md b/plugins/aws-agent-payments/skills/x402-payments/SKILL.md new file mode 100644 index 00000000..db5c0d53 --- /dev/null +++ b/plugins/aws-agent-payments/skills/x402-payments/SKILL.md @@ -0,0 +1,183 @@ +--- +name: x402-payments +description: "Auto-pay x402-paywalled URLs using AWS AgentCore Payments. Handles HTTP 402 challenges, payment signing, and request replay for both v1 and v2 of the x402 protocol." +metadata: + tags: [x402, payments, paywall, usdc, crypto, web3, agentcore, micropayments] + version: "1.0.0" +--- + +# x402 Payments + +This skill enables AI agents to auto-pay x402-paywalled URLs using AWS AgentCore Payments. It is agent-host independent — it describes the protocol and tool interactions generically, working the same whether tools are exposed as direct functions, MCP tools, or namespaced actions. + +## Tool Inventory + +The x402 payment system provides five tools. Match them by role — your runtime may prefix or rename them: + +| Role | Typical name | Purpose | +| ----------------------- | ---------------------------- | --------------------------------------------------------- | +| Infrastructure setup | `setup_x402_payments` | One-shot creation of Payment Manager, Connector, Wallet | +| Session status check | `get_payment_session_status` | Check if current session is usable | +| Session creation | `create_payment_session` | Mint a fresh session with budget (requires user approval) | +| Server-side pay + fetch | `get_paid_content` | Pay and return content in one call | +| Header-only payment | `pay_and_get_header` | Mint payment header for browser replay | + +## When to Use + +Activate this skill when **any** of these occur: + +- An HTTP request returns 402 with x402 challenge headers (`x402Version`, `Payment-Required`, or `x-payment-required`) +- The user asks to access content from a URL they identify as x402-paywalled +- The user asks to "set up x402 payments" or "configure agent payments" +- A tool call fails with 402 Payment Required + +Do NOT use for: + +- Login walls, captchas, or non-x402 paywalls +- AWS billing or cost management +- Stripe checkout / e-commerce payments + +## Protocol + +### Step 1: Check Payment Session + +Call the **session-status** tool. The response includes a `usable` boolean. + +- **If `usable: true`** → proceed to Step 3 +- **If `usable: false`** → the session is expired, drained, or doesn't exist. Go to Step 2. + +### Step 2: Request User Approval for New Session + +**Never mint a session without explicit user approval.** Each session sets a spending budget that the agent can use. + +Tell the user: + +> Your payment session is [expired/drained/missing]. I can create a new one with a $5 budget valid for 4 hours. Would you like to approve this? + +On approval, call the **create-session** tool with `max_spend_usd="5"` and `expiry_minutes=240` (or user-specified values). Always ask for budget and duration confirmation before proceeding. + +### Step 3: Pay for the URL + +**Preferred path (server-side):** Call `get_paid_content` with the URL. The tool: + +1. Probes the URL → gets 402 + x402 challenge +2. Calls AgentCore ProcessPayment → gets signed payment header +3. Replays the request with the payment header +4. Returns `{status_code, content_type, body, url}` + +Read the content from the `body` field. No second request needed. + +**Alternative path (browser/header-only):** If you need the page rendered in a live browser: + +1. Call `pay_and_get_header` → returns `{header: {"X-PAYMENT": "VALUE"}, valid_seconds: }` +2. Set the header on your browser context +3. Navigate to the URL again — replay immediately, header validity is time-limited +4. The paid page renders normally + +### Step 4: Handle Errors + +- **Session expired mid-request** → go back to Step 2 +- **Still 402 after payment** → session may have drained; check session status before retrying, then mint a new session if balance is zero +- **Header expired** → call `pay_and_get_header` again + +For detailed error diagnosis, see [references/debugging.md](references/debugging.md). + +## First-Time Setup + +If no payment infrastructure exists, use the **setup** tool. For detailed prerequisites and IAM configuration, see [references/setup.md](references/setup.md). + +Required inputs: + +- `role_arn` — IAM role with `bedrock-agentcore.amazonaws.com` trust policy +- Wallet provider credentials (stored securely in AWS Secrets Manager, never in transcripts) +- Optional: `region` (default us-east-1), `network` (default eip155:84532), `user_id` + +After setup: + +1. Provide the redirect URL for delegated signing authorization +2. Instruct the user to fund the wallet with USDC on the target network + +## x402 Protocol Details + +For the full protocol specification including v2 envelope format, supported assets, and chain IDs, see [references/protocol.md](references/protocol.md). + +## Guidelines + +- **Don't surface payment internals** — report the content, not transaction hashes or header bytes +- **Always check session status first** — avoids `ExpiredTokenException` errors +- **Never auto-mint sessions** — get explicit user approval each time (unless user previously authorized auto-creation) +- **Wallet credentials must never appear in tool parameters or transcripts** — read from environment or secure config at execution time +- **Verify session balance before retrying** — a retry after failure should confirm the session still has funds rather than blindly calling ProcessPayment again + +## Session Consent Enforcement + +`CreatePaymentSession` is the spending-authorization boundary — whoever calls it controls how much the agent can spend. If the agent can create sessions autonomously, it can bypass budget controls by minting new sessions indefinitely. + +**Recommended enforcement (strongest → weakest):** + +| Tier | Mechanism | Guarantee | +|------|-----------|----------| +| 1 | **Host-native approval gate** — the agent host intercepts `CreatePaymentSession` and surfaces an Approve/Deny prompt to the user. The LLM cannot bypass this. | Hard | +| 2 | **IAM role separation** — the agent's runtime role only has `ProcessPayment` + `GetPaymentSession`. Sessions are created out-of-band by a human or privileged process. | Hard | +| 3 | **Conversational confirmation** — the agent asks the user "Create a $5 session?" and waits for affirmative response. | Soft (LLM-enforceable only) | + +**Recommendations:** + +- For **unattended/autonomous agents**: use Tier 1 or Tier 2. Tier 3 alone is insufficient — a jailbroken or confused model could self-approve. +- For **interactive chat agents with a human present**: Tier 1 (host approval gate) is ideal. Tier 3 is acceptable as a fallback if the host lacks native approval. +- For **developer/CLI workflows**: session creation should be a human-run script outside the LLM loop entirely (Tier 2). + +**Host-specific implementations:** + +- **OpenClaw**: `create_payment_session` uses a two-phase confirmation gate. The first call returns `AWAITING_USER_APPROVAL` and the agent must present the budget/duration to the user. Only after explicit approval does the second call (with `confirmed: true`) execute. +- **Strands/LangGraph**: Use IAM role separation (Tier 2). The `setup_payment_user.py` script creates sessions in the terminal; the agent runtime role lacks `CreatePaymentSession`. +- **Custom hosts**: Implement a pre-execution hook on `CreatePaymentSession` that gates on user confirmation via your application's consent mechanism. + +## Fallback (No Runtime Plugin) + +If runtime tools (`get_paid_content`, `pay_and_get_header`) are not available, use the AWS CLI directly: + +### Check/Create Session + +```bash +# Check existing session +aws bedrock-agentcore get-payment-session \ + --payment-manager-arn $PM_ARN \ + --payment-session-id $SESSION_ID \ + --user-id $USER_ID \ + --region us-east-1 + +# Create new session (requires user approval for budget) +aws bedrock-agentcore create-payment-session \ + --payment-manager-arn $PM_ARN \ + --user-id $USER_ID \ + --budget '{"maxSpendUsd": "5.00"}' \ + --ttl-minutes 240 \ + --region us-east-1 +``` + +### Process Payment + +```bash +# After receiving a 402 with x402 challenge, extract the accepts[0] object and call: +aws bedrock-agentcore process-payment \ + --payment-manager-arn $PM_ARN \ + --payment-session-id $SESSION_ID \ + --payment-instrument-id $INSTRUMENT_ID \ + --user-id $USER_ID \ + --payment-type CRYPTO_X402 \ + --payment-input '{"cryptoX402": {"version": "2", "payload": }}' \ + --region us-east-1 +``` + +The response contains `paymentOutput.cryptoX402.payload` — base64-encode it and set as the `X-PAYMENT` header on the retry request. + +## Verification + +The skill succeeded if the agent: + +1. Detected the 402 +2. Paid transparently +3. Returned the paid content to the user + +The user should never see "Payment Required" as a final error. diff --git a/plugins/aws-agent-payments/skills/x402-payments/references/debugging.md b/plugins/aws-agent-payments/skills/x402-payments/references/debugging.md new file mode 100644 index 00000000..c214de5a --- /dev/null +++ b/plugins/aws-agent-payments/skills/x402-payments/references/debugging.md @@ -0,0 +1,83 @@ +# Debugging Reference + +## Common Issues + +### "PaymentSessionExpired" or "ExpiredTokenException" + +**Cause:** Session TTL exceeded or session was never created. + +**Fix:** + +1. Call `get_payment_session_status` to confirm status +2. Ask user to approve a new session +3. Call `create_payment_session` with desired cap/TTL + +### "Still 402 after payment" + +**Cause:** The payment was processed but on-chain settlement has not propagated, or the session was drained between the status check and the payment attempt. + +**Fix:** + +- Check session status first — if `remaining_usd` is 0 or near-zero, create a new session +- If session has funds, wait a few seconds and retry `get_paid_content` once +- Note: each retry generates a new payment (ProcessPayment calls are NOT automatically idempotent unless the implementation passes a stable `clientToken`) +- Verify wallet has sufficient USDC on the correct network + +### "InvalidSignature" or signing failures + +**Cause:** Wallet instrument or connector misconfigured. + +**Fix:** + +1. Verify delegated signing was authorized (the redirect URL step) +2. Check that the wallet secret matches what was provided during setup +3. Confirm the connector type matches the credential provider + +### "NetworkMismatch" + +**Cause:** The x402 endpoint expects a different network than what the wallet was created on. + +**Fix:** + +- Check the endpoint's `accepts` array for required network +- If the wallet was created on a different network, a new instrument is needed on the correct network +- Ensure wallet is funded on that specific network + +### "AccessDeniedException" on ProcessPayment + +**Cause:** IAM permissions insufficient. + +**Fix:** + +- Verify the calling identity has `bedrock-agentcore:ProcessPayment` permission +- Check the resource ARN matches the Payment Manager +- Verify the region matches + +### Setup tool fails with "CredentialProviderAlreadyExists" + +**Cause:** A credential provider with that name already exists. + +**Fix:** + +- Re-run setup — the tool generates unique names with timestamp suffixes +- If collision persists, delete the old one via AWS CLI: + + ```bash + aws bedrock-agentcore-control delete-credential-provider \ + --payment-manager-id PM_ID \ + --credential-provider-id CP_ID \ + --region REGION + ``` + +## Diagnostic Steps + +1. **Check session:** `get_payment_session_status` → look at `usable`, `remaining_usd`, `minutes_left` +2. **Check wallet funding:** Verify USDC balance on block explorer for the wallet address +3. **Check AWS credentials:** `aws sts get-caller-identity` → confirm correct account/role +4. **Check region:** Ensure Payment Manager region matches the config +5. **Check network:** Confirm endpoint's required network matches the wallet's network + +## Logs + +- **CloudTrail:** All AgentCore API calls logged (ProcessPayment, CreatePaymentSession, etc.) +- **Agent host logs:** Check for HTTP 402 response bodies — they contain the x402 challenge details diff --git a/plugins/aws-agent-payments/skills/x402-payments/references/protocol.md b/plugins/aws-agent-payments/skills/x402-payments/references/protocol.md new file mode 100644 index 00000000..260959b5 --- /dev/null +++ b/plugins/aws-agent-payments/skills/x402-payments/references/protocol.md @@ -0,0 +1,138 @@ +# x402 Protocol Reference + +## How x402 Works + +x402 is a standard HTTP payment protocol that extends HTTP 402 (Payment Required) with machine-readable payment challenges. When a server protects content behind a paywall: + +1. Client makes a normal HTTP request +2. Server returns HTTP 402 with payment challenge headers +3. Client processes payment (signs a blockchain transaction) +4. Client replays the request with a payment proof header +5. Server verifies the proof and returns the content + +## x402 Version 2 (Current) + +This skill targets x402 v2, which is the actively deployed protocol version. + +- **Challenge delivery:** `Payment-Required` header (base64 JSON) OR JSON response body with `x402Version: "2"` +- **Payment header:** `X-PAYMENT` with base64-encoded PaymentPayload envelope +- **Multiple accepted payment schemes** per challenge via structured `accepts` array + +### Payment Flow (v2) + +**1. Server sends 402 with challenge:** + +```json +{ + "x402Version": 2, + "resource": { "url": "...", "description": "...", "mimeType": "..." }, + "accepts": [ + { + "scheme": "exact", + "network": "eip155:84532", + "amount": "100000", + "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", + "payTo": "0x...", + "maxTimeoutSeconds": 60 + } + ] +} +``` + +**2. Agent calls AgentCore ProcessPayment:** + +```json +{ + "paymentManagerArn": "arn:aws:bedrock-agentcore:...:payment-manager/...", + "paymentSessionId": "...", + "paymentInstrumentId": "...", + "userId": "...", + "clientToken": "", + "paymentType": "CRYPTO_X402", + "paymentInput": { + "cryptoX402": { + "version": "2", + "payload": {/* accepts[0] object from challenge */} + } + } +} +``` + +**3. AgentCore returns signed payload:** + +```json +{ + "paymentOutput": { + "cryptoX402": { + "payload": { + "signature": "0x...", + "authorization": { + "from": "", + "to": "", + "value": "", + "validAfter": "", + "validBefore": "", + "nonce": "" + } + } + } + } +} +``` + +**4. Agent replays request with X-PAYMENT header:** + +``` +X-PAYMENT: +``` + +### Challenge `accepts` Array + +Each entry in `accepts` describes one payment option the server will accept: + +| Field | Description | +| ------------------- | ---------------------------------------------------------- | +| `scheme` | Payment scheme (e.g., `"exact"`) | +| `network` | Chain identifier (e.g., `"eip155:84532"` for Base Sepolia) | +| `amount` | Amount in base units (e.g., `"100000"` for $0.10 USDC) | +| `asset` | Token contract address | +| `payTo` | Recipient address | +| `maxTimeoutSeconds` | Maximum time for payment validity | +| `extra` | Optional additional parameters | + +## AgentCore ProcessPayment + +The AgentCore Payments API handles the cryptographic signing: + +**Input (`paymentInput.cryptoX402`):** + +- `version` — protocol version ("2") +- `payload` — the `accepts[0]` object from the x402 challenge + +**Output (`paymentOutput.cryptoX402`):** + +- `payload` — signed payment object containing `authorization` + `signature` fields + +The output payload is base64-encoded and sent as the `X-PAYMENT` header value. + +## Supported Asset Addresses + +| Network | Asset | Address | +| ------------ | ----- | -------------------------------------------- | +| Base Sepolia | USDC | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` | +| Base Mainnet | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | + +## Security Considerations + +- **Redirect safety:** Payment proof headers should NOT follow cross-origin redirects. The replay request should use `redirect: "manual"` and only re-attach the payment header if the redirect target's origin matches the original challenge origin. +- **Credential handling:** Wallet signing keys must never be passed as tool parameters or stored in conversation transcripts. Use environment variables or secure credential files. +- **Idempotency:** ProcessPayment supports a `clientToken` for idempotent retries. Implementations should derive a stable token from the challenge (e.g., hash of resource URL + amount + nonce) rather than relying on SDK auto-generation. + +## Error Codes + +| Error | Meaning | Resolution | +| ----------------------- | -------------------------- | --------------------------------------- | +| `PaymentSessionExpired` | Session TTL exceeded | Create new session | +| `InsufficientBalance` | Session spend cap reached | Create new session with higher cap | +| `InvalidSignature` | Wallet signing failed | Check instrument/connector setup | +| `NetworkMismatch` | Wrong network for endpoint | Verify wallet network matches challenge | diff --git a/plugins/aws-agent-payments/skills/x402-payments/references/setup.md b/plugins/aws-agent-payments/skills/x402-payments/references/setup.md new file mode 100644 index 00000000..75498e83 --- /dev/null +++ b/plugins/aws-agent-payments/skills/x402-payments/references/setup.md @@ -0,0 +1,131 @@ +# Setup Reference + +## Prerequisites + +### AWS Account Setup + +1. **Enable AgentCore Payments** in your AWS account — see [region availability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html) +2. **Create IAM roles** — see [AgentCore Payments IAM roles best practices](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html) + +**Recommended: Separate IAM roles for setup vs runtime.** This follows the principle of least privilege: + +- **Setup role** (used once): `CreatePaymentManager`, `CreatePaymentCredentialProvider`, `CreatePaymentConnector`, `CreatePaymentInstrument` +- **Agent runtime role** (used in production): `ProcessPayment`, `GetPaymentSession`, `CreatePaymentSession` + +This separation ensures that the running agent cannot modify its own payment infrastructure. + +**Setup role trust policy:** + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Service": "bedrock-agentcore.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] +} +``` + +3. **Attach permissions** to the role: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:CreatePaymentCredentialProvider", + "bedrock-agentcore:CreatePaymentManager", + "bedrock-agentcore:GetPaymentManager", + "bedrock-agentcore:CreatePaymentConnector", + "bedrock-agentcore:CreatePaymentInstrument", + "bedrock-agentcore:CreatePaymentSession", + "bedrock-agentcore:ProcessPayment", + "bedrock-agentcore:GetPaymentSession", + "bedrock-agentcore:GetPaymentInstrument" + ], + "Resource": "*" + }, + { + "Effect": "Allow", + "Action": [ + "secretsmanager:CreateSecret", + "secretsmanager:PutSecretValue" + ], + "Resource": "arn:aws:secretsmanager:*:*:secret:agentcore-payments-*" + } + ] +} +``` + +### Coinbase CDP Setup + +1. Create account at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com) +2. Create a project +3. Generate an API key → note the **Key ID** (UUID) and **Key Secret** (Ed25519 base64) +4. Generate a **Wallet Secret** (for signing) +5. Under Wallet > Embedded Wallets > Policies, **enable Delegated signing** + +**Important: Credentials must NEVER be passed as tool parameters to the LLM.** Store all credentials in environment variables or a `.env` file local to your machine: + +```bash +# .env (add to .gitignore!) +CDP_API_KEY_ID=your-key-id +CDP_API_KEY_SECRET=your-key-secret +CDP_WALLET_SECRET=your-wallet-secret +``` + +The plugin reads these from the environment at execution time. The LLM never sees or processes the raw credential values — only the agent host process has access. Never include wallet secrets in conversation transcripts, tool invocations, or config files checked into source control. + +### Stripe/Privy Setup + +1. Create account at [dashboard.privy.io](https://dashboard.privy.io) +2. Create an app → note the **App ID** and **App Secret** +3. Generate authorization credentials → **Auth ID** and **Auth Private Key** + +## Resource Naming Rules + +- **Credential Provider names**: lowercase alphanumeric + hyphens only (`[a-z0-9-]+`). NO underscores. +- **Connector names**: start with letter, alphanumeric + underscores (`[a-zA-Z][a-zA-Z0-9_]*`) +- **Payment Manager names**: alphanumeric + hyphens, start with letter + +## Post-Setup Steps + +After infrastructure creation: + +1. **Authorize delegated signing** — open the redirect URL provided by the setup tool +2. **Fund the wallet** — send USDC to the wallet address on the target network + - Base Sepolia: use [faucet.circle.com](https://faucet.circle.com/) (select Base Sepolia) + - Base Mainnet: send USDC via any exchange or bridge +3. **Create a payment session** — the agent handles this automatically on first use + +## Scoping Down Agent Permissions + +For production, the running agent only needs: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:ProcessPayment", + "bedrock-agentcore:GetPaymentSession", + "bedrock-agentcore:CreatePaymentSession", + "bedrock-agentcore:GetPaymentInstrument" + ], + "Resource": [ + "arn:aws:bedrock-agentcore:REGION:ACCOUNT:payment-manager/PM_ID", + "arn:aws:bedrock-agentcore:REGION:ACCOUNT:payment-manager/PM_ID/*" + ] + } + ] +} +``` diff --git a/tools/generate_codex_manifests.py b/tools/generate_codex_manifests.py index 37e0e310..971f0b57 100644 --- a/tools/generate_codex_manifests.py +++ b/tools/generate_codex_manifests.py @@ -20,6 +20,7 @@ CATEGORY_LABELS = { "ai": "AI", "fullstack": "Full Stack", + "payments": "Payments", } INTERFACE_METADATA = { @@ -103,6 +104,16 @@ "Review this ML setup for SageMaker best practices.", ], }, + "aws-agent-payments": { + "displayName": "AWS Agent Payments (x402)", + "shortDescription": "Pay for x402-paywalled APIs and content via AgentCore Payments.", + "longDescription": "Enable agents to transparently pay for x402-paywalled APIs, MCP tools, and web content via microtransactions using AWS AgentCore Payments.", + "defaultPrompt": [ + "Pay for this x402-paywalled URL.", + "Set up x402 payments with my Coinbase CDP credentials.", + "Check my payment session status.", + ], + }, }