aws · aidandaly24 · May 11, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -32,9 +32,9 @@ These options are available on all commands:
 
 - `create` - Create new AgentCore project
 - `add` - Add resources (agent, memory, credential, evaluator, online-eval, gateway, gateway-target, policy-engine,
-  policy)
+  policy, payment-manager, payment-connector)
 - `remove` - Remove resources (agent, memory, credential, evaluator, online-eval, gateway, gateway-target,
-  policy-engine, policy, all)
+  policy-engine, policy, payment-manager, payment-connector, all)
 - `deploy` - Deploy infrastructure to AWS
 - `status` - Check deployment status
 - `dev` - Local development server (CodeZip: uvicorn with hot-reload; Container: Docker build + run with volume mount)
@@ -88,6 +88,8 @@ Current primitives:
 - `GatewayTargetPrimitive` — gateway target creation/removal with code generation
 - `PolicyEnginePrimitive` — Cedar policy engine creation/removal
 - `PolicyPrimitive` — Cedar policy creation/removal within policy engines
+- `PaymentManagerPrimitive` — payment manager creation/removal with agent code wiring
+- `PaymentConnectorPrimitive` — payment connector creation/removal with credential management
 
 Singletons are created in `registry.ts` and wired into CLI commands via `cli.ts`. See `src/cli/AGENTS.md` for details on
 adding new primitives.

diff --git a/docs/commands.md b/docs/commands.md
@@ -139,14 +139,14 @@ agentcore status --runtime-id abc123
 agentcore status --json
 ```
 
-| Flag                | Description                                                                                                                |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `--runtime-id <id>` | Look up a specific runtime by ID                                                                                           |
-| `--target <name>`   | Select deployment target                                                                                                   |
-| `--type <type>`     | Filter by resource type: `agent`, `memory`, `credential`, `gateway`, `evaluator`, `online-eval`, `policy-engine`, `policy` |
-| `--state <state>`   | Filter by deployment state: `deployed`, `local-only`, `pending-removal`                                                    |
-| `--runtime <name>`  | Filter to a specific runtime                                                                                               |
-| `--json`            | JSON output                                                                                                                |
+| Flag                | Description                                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `--runtime-id <id>` | Look up a specific runtime by ID                                                                                                      |
+| `--target <name>`   | Select deployment target                                                                                                              |
+| `--type <type>`     | Filter by resource type: `agent`, `memory`, `credential`, `gateway`, `evaluator`, `online-eval`, `payment`, `policy-engine`, `policy` |
+| `--state <state>`   | Filter by deployment state: `deployed`, `local-only`, `pending-removal`                                                               |
+| `--runtime <name>`  | Filter to a specific runtime                                                                                                          |
+| `--json`            | JSON output                                                                                                                           |
 
 ### validate
 
@@ -472,6 +472,85 @@ agentcore add gateway-target \
 > `open-api-schema` requires `--outbound-auth` (`oauth` or `api-key`). `api-gateway` supports `api-key` or `none`.
 > `mcp-server` supports `oauth` or `none`.
 
+### add payment-manager
+
+Add a payment manager to the project. See [Payments](payments.md) for full usage guide.
+
+```bash
+# Minimal (defaults: AWS_IAM, interceptor, auto-payment enabled)
+agentcore add payment-manager --name MyManager
+
+# With CUSTOM_JWT authorization
+agentcore add payment-manager \
+  --name MyManager \
+  --authorizer-type CUSTOM_JWT \
+  --discovery-url https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration \
+  --allowed-clients "client-id-1,client-id-2"
+
+# With advanced options
+agentcore add payment-manager \
+  --name MyManager \
+  --auto-payment true \
+  --default-spend-limit 25.00 \
+  --tool-allowlist "web_search,fetch_url" \
+  --network-preferences "eip155:84532"
+```
+
+| Flag                               | Description                                           |
+| ---------------------------------- | ----------------------------------------------------- |
+| `--name <name>`                    | Manager name (required in non-interactive mode)       |
+| `--authorizer-type <type>`         | `AWS_IAM` (default) or `CUSTOM_JWT`                   |
+| `--discovery-url <url>`            | OIDC discovery URL (required for CUSTOM_JWT)          |
+| `--allowed-clients <clients>`      | Comma-separated client IDs (CUSTOM_JWT only)          |
+| `--allowed-audience <audience>`    | Comma-separated allowed audiences (CUSTOM_JWT only)   |
+| `--allowed-scopes <scopes>`        | Comma-separated allowed scopes (CUSTOM_JWT only)      |
+| `--pattern <pattern>`              | `interceptor` (default) or `tool-based`               |
+| `--auto-payment [value]`           | Enable automatic payment: `true` (default) or `false` |
+| `--default-spend-limit <amount>`   | Default session spend limit in USD (default: `10.00`) |
+| `--tool-allowlist <tools>`         | Comma-separated tool names eligible for payment       |
+| `--network-preferences <networks>` | Comma-separated network IDs (e.g., `eip155:84532`)    |
+| `--description <desc>`             | Human-readable description                            |
+| `--json`                           | JSON output                                           |
+
+### add payment-connector
+
+Add a payment connector to an existing payment manager. See [Payments](payments.md) for credential details.
+
+```bash
+# CoinbaseCDP provider
+agentcore add payment-connector \
+  --manager MyManager \
+  --name MyCDPConnector \
+  --provider CoinbaseCDP \
+  --api-key-id your-api-key-id \
+  --api-key-secret your-api-key-secret \
+  --wallet-secret your-wallet-secret
+
+# StripePrivy provider
+agentcore add payment-connector \
+  --manager MyManager \
+  --name MyStripeConnector \
+  --provider StripePrivy \
+  --app-id your-app-id \
+  --app-secret your-app-secret \
+  --authorization-private-key your-private-key \
+  --authorization-id your-auth-id
+```
+
+| Flag                                | Description                                |
+| ----------------------------------- | ------------------------------------------ |
+| `--manager <name>`                  | Parent payment manager (required)          |
+| `--name <name>`                     | Connector name (required)                  |
+| `--provider <provider>`             | `CoinbaseCDP` (default) or `StripePrivy`   |
+| `--api-key-id <id>`                 | Coinbase CDP API Key ID                    |
+| `--api-key-secret <secret>`         | Coinbase CDP API Key Secret                |
+| `--wallet-secret <secret>`          | Coinbase CDP Wallet Secret                 |
+| `--app-id <id>`                     | Privy App ID (StripePrivy)                 |
+| `--app-secret <secret>`             | Privy App Secret (StripePrivy)             |
+| `--authorization-private-key <key>` | ECDSA P-256 private key (StripePrivy)      |
+| `--authorization-id <id>`           | Authorization key identifier (StripePrivy) |
+| `--json`                            | JSON output                                |
+
 ### add credential
 
 Add a credential to the project. Supports API key and OAuth credential types.
@@ -659,19 +738,22 @@ agentcore remove gateway-target --name WeatherTools
 agentcore remove policy-engine --name MyPolicyEngine
 agentcore remove policy --name AdminAccess --engine MyPolicyEngine
 agentcore remove runtime-endpoint --name prod
+agentcore remove payment-manager --name MyManager -y
+agentcore remove payment-connector --name MyCDPConnector --manager MyManager -y
 
 # Reset everything
 agentcore remove all -y
 agentcore remove all --dry-run  # Preview
 ```
 
-| Flag                | Description                                       |
-| ------------------- | ------------------------------------------------- |
-| `--name <name>`     | Resource name                                     |
-| `--engine <engine>` | Policy engine name (required for `remove policy`) |
-| `-y, --yes`         | Skip confirmation                                 |
-| `--dry-run`         | Preview (`remove all` only)                       |
-| `--json`            | JSON output                                       |
+| Flag                | Description                                               |
+| ------------------- | --------------------------------------------------------- |
+| `--name <name>`     | Resource name                                             |
+| `--engine <engine>` | Policy engine name (required for `remove policy`)         |
+| `--manager <name>`  | Parent payment manager (required for `payment-connector`) |
+| `-y, --yes`         | Skip confirmation                                         |
+| `--dry-run`         | Preview (`remove all` only)                               |
+| `--json`            | JSON output                                               |
 
 ---
 
@@ -735,23 +817,26 @@ agentcore invoke --exec "cat /etc/os-release" --json
 The prompt can come from four sources, resolved in this precedence order: `--prompt` > positional > `--prompt-file` >
 piped stdin. `--prompt-file` combined with piped stdin content returns a collision error — pick one.
 
-| Flag                   | Description                                                      |
-| ---------------------- | ---------------------------------------------------------------- |
-| `[prompt]`             | Prompt text (positional argument)                                |
-| `--prompt <text>`      | Prompt text (flag, takes precedence over positional)             |
-| `--prompt-file <path>` | Read the prompt from a file (useful for long / structured input) |
-| `--runtime <name>`     | Specific runtime                                                 |
-| `--target <name>`      | Deployment target                                                |
-| `--session-id <id>`    | Continue a specific session                                      |
-| `--user-id <id>`       | User ID for runtime invocation (default: `default-user`)         |
-| `--stream`             | Stream response in real-time                                     |
-| `--tool <name>`        | MCP tool name (use with `call-tool` prompt)                      |
-| `--input <json>`       | MCP tool arguments as JSON (use with `--tool`)                   |
-| `-H, --header <h>`     | Custom header (`"Name: Value"`, repeatable)                      |
-| `--bearer-token <t>`   | Bearer token for CUSTOM_JWT auth                                 |
-| `--exec`               | Execute a shell command in the runtime container                 |
-| `--timeout <seconds>`  | Timeout in seconds for `--exec` commands                         |
-| `--json`               | JSON output                                                      |
+| Flag                           | Description                                                      |
+| ------------------------------ | ---------------------------------------------------------------- |
+| `[prompt]`                     | Prompt text (positional argument)                                |
+| `--prompt <text>`              | Prompt text (flag, takes precedence over positional)             |
+| `--prompt-file <path>`         | Read the prompt from a file (useful for long / structured input) |
+| `--runtime <name>`             | Specific runtime                                                 |
+| `--target <name>`              | Deployment target                                                |
+| `--session-id <id>`            | Continue a specific session                                      |
+| `--user-id <id>`               | User ID for runtime invocation (default: `default-user`)         |
+| `--stream`                     | Stream response in real-time                                     |
+| `--tool <name>`                | MCP tool name (use with `call-tool` prompt)                      |
+| `--input <json>`               | MCP tool arguments as JSON (use with `--tool`)                   |
+| `-H, --header <h>`             | Custom header (`"Name: Value"`, repeatable)                      |
+| `--bearer-token <t>`           | Bearer token for CUSTOM_JWT auth                                 |
+| `--payment-instrument-id <id>` | Payment instrument ID for x402 payments                          |
+| `--payment-session-id <id>`    | Payment session ID for budget tracking                           |
+| `--auto-session`               | Auto-create/reuse a payment session for testing                  |
+| `--exec`                       | Execute a shell command in the runtime container                 |
+| `--timeout <seconds>`          | Timeout in seconds for `--exec` commands                         |
+| `--json`                       | JSON output                                                      |
 
 Piped stdin is auto-detected: when no prompt is supplied and stdin is not a TTY, the prompt is read from stdin.
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -38,6 +38,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
   ],
   "memories": [],
   "credentials": [],
+  "payments": [],
   "evaluators": [],
   "onlineEvalConfigs": [],
   "agentCoreGateways": [],
@@ -57,6 +58,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
 | `credentials`       | Yes      | Array of credential providers (API key or OAuth)            |
 | `evaluators`        | Yes      | Array of custom evaluator definitions                       |
 | `onlineEvalConfigs` | Yes      | Array of online eval configurations                         |
+| `payments`          | No       | Array of payment manager configurations                     |
 | `policyEngines`     | No       | Array of policy engine configurations                       |
 | `agentCoreGateways` | No       | Array of gateway definitions                                |
 | `mcpRuntimeTools`   | No       | Array of MCP runtime tool definitions                       |
@@ -482,6 +484,88 @@ implementations.
 
 ---
 
+## Payment Manager Resource
+
+Payment managers define how agents handle x402 microtransactions. Each manager has one or more connectors that provide
+wallet credentials. See [Payments](payments.md) for the full usage guide.
+
+```json
+{
+  "payments": [
+    {
+      "name": "MyManager",
+      "authorizerType": "AWS_IAM",
+      "pattern": "interceptor",
+      "autoPayment": true,
+      "defaultSpendLimit": "10.00",
+      "paymentToolAllowlist": ["web_search", "fetch_url"],
+      "networkPreferences": ["eip155:84532"],
+      "description": "Production payment manager",
+      "connectors": [
+        {
+          "name": "MyCDPConnector",
+          "provider": "CoinbaseCDP",
+          "credentialName": "my-cdp-creds"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Payment Manager Fields
+
+| Field                     | Required | Description                                                          |
+| ------------------------- | -------- | -------------------------------------------------------------------- |
+| `name`                    | Yes      | Manager name (alphanumeric + underscore, max 48, starts with letter) |
+| `authorizerType`          | No       | `"AWS_IAM"` (default) or `"CUSTOM_JWT"`                              |
+| `authorizerConfiguration` | Cond.    | Required when `authorizerType` is `"CUSTOM_JWT"` (see below)         |
+| `pattern`                 | No       | `"interceptor"` (default) or `"tool-based"`                          |
+| `connectors`              | Yes      | Array of payment connector objects                                   |
+| `autoPayment`             | No       | Enable automatic payment (default: `true`)                           |
+| `defaultSpendLimit`       | No       | Default session budget in USD (e.g., `"10.00"`)                      |
+| `paymentToolAllowlist`    | No       | Array of tool names eligible for payment                             |
+| `networkPreferences`      | No       | Array of network identifiers (e.g., `"eip155:84532"`)                |
+| `description`             | No       | Human-readable description                                           |
+
+### Authorizer Configuration (CUSTOM_JWT)
+
+```json
+{
+  "authorizerConfiguration": {
+    "customJWTAuthorizer": {
+      "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration",
+      "allowedClients": ["client-id-1"],
+      "allowedAudience": ["https://api.example.com"],
+      "allowedScopes": ["payments:read", "payments:write"]
+    }
+  }
+}
+```
+
+| Field             | Required | Description                 |
+| ----------------- | -------- | --------------------------- |
+| `discoveryUrl`    | Yes      | OIDC discovery URL          |
+| `allowedClients`  | No       | Array of allowed client IDs |
+| `allowedAudience` | No       | Array of allowed audiences  |
+| `allowedScopes`   | No       | Array of allowed scopes     |
+
+### Payment Connector
+
+| Field            | Required | Description                                        |
+| ---------------- | -------- | -------------------------------------------------- |
+| `name`           | Yes      | Connector name (alphanumeric + underscore, max 48) |
+| `provider`       | No       | `"CoinbaseCDP"` (default) or `"StripePrivy"`       |
+| `credentialName` | Yes      | Name of the credential (maps to `.env.local` vars) |
+
+### Payment Credential Provider
+
+Payment connectors use a `PaymentCredentialProvider` credential type, distinct from `ApiKeyCredentialProvider` and
+`OAuthCredentialProvider`. The credential is automatically created during `agentcore deploy` from values in
+`.env.local`. You do not need to add it to the `credentials` array manually.
+
+---
+
 ## aws-targets.json
 
 Deployment target
@@ -524,6 +608,19 @@ AGENTCORE_CREDENTIAL_{projectName}GEMINI=...
 # OAuth credentials
 AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_ID=my-client-id
 AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_SECRET=my-client-secret
+
+# Payment credentials - CoinbaseCDP (3 variables per connector)
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_ID=your-api-key-id
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_SECRET=your-api-key-secret
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_WALLET_SECRET=your-wallet-secret
+
+# Payment credentials - StripePrivy (4 variables per connector)
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_ID=your-app-id
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_SECRET=your-app-secret
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_PRIVATE_KEY=your-private-key
+AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_ID=your-auth-id
 ```
 
-Environment variable names should match the credential names in your configuration.
+Environment variable names should match the credential names in your configuration. For payment credentials,
+`{CREDENTIAL_NAME}` is the connector's `credentialName` uppercased with hyphens replaced by underscores (e.g.,
+`my-cdp-creds` becomes `MY_CDP_CREDS`). See [Payments](payments.md#credential-storage) for details.