Using the AgentCore Payments skill Using CLI, SDK, or Boto3 Troubleshooting Cleanup What you’ve built Next steps

AgentCore payments quick start

This tutorial walks you through setting up AgentCore payments and processing your first microtransaction. By the end, your agent will pay for a resource using the x402 protocol on a test network.

You can set up payments in two ways:

Using the AgentCore Payments skill — An automated setup experience that provisions all resources through a guided conversation with AI coding agents like Kiro, Claude Code, or Codex. The skill handles CLI commands, SDK scripts, and framework wiring for you.
Using CLI, SDK, or Boto3 — A step-by-step manual setup using the AgentCore CLI, AWS SDK, or AWS CLI directly.

Using the AgentCore Payments skill

The AgentCore Payments skill automates the entire setup process through an interactive, guided experience. It provisions the following resources:

PaymentCredentialProvider — Stores payment provider credentials in AgentCore Identity.
Payment Manager — The top-level resource that coordinates payment operations.
Payment Connector — Links the manager to your credentials via the AgentCore CLI.
Payment Instrument — A crypto wallet that your agent uses to pay merchants on behalf of a user.
Payment Session — A time-bounded context with spending limits.

The skill also wires payments into your agent with a framework-agnostic tool, so it works with Strands, LangGraph, OpenAI Agents SDK, or any Python framework.

Prerequisites

Before starting, make sure you have:

AWS Account with credentials configured (aws configure)
An AWS Region where AgentCore payments is available — us-east-1, us-west-2, eu-central-1, or ap-southeast-2. See Supported AWS Regions.
Node.js 20+ installed (the skill installs the AgentCore CLI automatically)
An agent that accesses a paid endpoint — The skill enables your agent to pay for x402-protected APIs. For testing, you can use the sandbox endpoint https://sandbox.node4all.com/v1/x402-test.
The Agent Toolkit for AWS aws-agents plugin installed in your AI coding agent:
Example
Claude Code

/plugin marketplace add aws/agent-toolkit-for-aws /plugin install aws-agents@agent-toolkit-for-aws

Codex

The plugin is discovered automatically from the marketplace manifest. To add the marketplace, run the following command:

codex plugin marketplace add aws/agent-toolkit-for-aws

Invoke the skill

The payments skill is part of the agents-build skill in the Agent Toolkit for AWS. To trigger it, describe your intent in your AI coding agent. For example:

"Add payments to my agent using agents-build skill in aws-agents plugin"
"Set up microtransactions for my agent using agents-build skill in aws-agents plugin"
"I need to handle 402 Payment Required responses using agents-build skill in aws-agents plugin"
"Wire my agent to pay for x402-protected APIs using agents-build skill in aws-agents plugin"

The skill detects payment-related intent and loads the payments workflow automatically.

What the skill does

The skill runs an automated process that provisions your payment infrastructure end-to-end. The skill runs most steps automatically and pauses twice for your input:

Verifies or installs the AgentCore CLI and sets up the project
Creates the payment manager
Pauses — You run agentcore add payment-connector to enter your provider secrets (Coinbase CDP or Stripe Privy credentials)
Deploys resources to your AWS account (agentcore deploy -y)
Wires a framework-agnostic payment tool (x402_payment_tool.py) into your agent
Creates a per-user wallet (instrument) and budget-bounded session via the SDK
Pauses — You authorize the wallet (delegation) and fund it with testnet USDC from the Circle faucet website
Sets environment variables and runs a test payment against a paid endpoint

Before running the connector command, obtain credentials from your provider:

Coinbase CDP — API Key ID, API Key Secret, and Wallet Secret from the Coinbase Developer Platform website (with Delegated signing enabled).
Stripe Privy — App ID, App Secret, Authorization ID, and Authorization Private Key from the Privy dashboard website.

A successful run shows the agent calling x402_fetch, detecting a 402, settling payment via the AgentCore SDK, and the retry returning 200 with paid content.

Using CLI, SDK, or Boto3

This section walks you through each step manually using the AgentCore CLI, AWS CLI, or AWS SDK (Boto3).

Prerequisites

Before starting, make sure you have:

AWS Account with credentials configured (aws configure)
Python 3.10+ installed
An AWS Region where AgentCore payments is available — us-east-1, us-west-2, eu-central-1, or ap-southeast-2. See Supported AWS Regions.

Install the required packages:


pip install boto3 bedrock-agentcore[strands-agents] strands-agents strands-agents-tools

Verify your credentials are configured:


aws sts get-caller-identity

Tip

If you have the AgentCore CLI v0.19.0 or later installed, you can use CLI commands as an alternative to the SDK in Steps 2, 3, 5, and 6. Each step below shows both options.

Step 1: Obtain payment provider credentials

AgentCore payments connects to an external payment provider for wallet operations. You need credentials from one of the supported providers before proceeding.

Example

Coinbase CDP

Log in to the Coinbase Developer Platform and create or select a project.
Generate an API key and note the API Key ID, API Key Secret, and Wallet Secret.
Under Project > Wallet > Embedded Wallets > Policies, enable Delegated signing.

You will use these three values in the next step:

Credential	Description
`API Key ID`	Public identifier for your CDP project
`API Key Secret`	Private secret for signing API requests
`Wallet Secret`	Secret for cryptographic wallet operations (deriving addresses, signing transactions)

Privy

Create a dedicated Privy app at dashboard.privy.io. Do not reuse apps that serve other purposes.
Copy the App ID and App Secret from your app settings.
Navigate to Wallet Infrastructure > Authorization and choose New Key to generate a P-256 key pair.
Strip the wallet-auth: prefix from the generated private key. Use only the raw base64 content.

You will use these four values in the next step:

Credential	Description
`App ID`	Your Privy application identifier
`App Secret`	Secret for server-to-server Basic Auth
`Authorization ID`	Public key identifier from the P-256 key pair
`Authorization Private Key`	Private key (base64 only, without the `wallet-auth:` prefix)

For full details including security best practices and credential rotation, see Prerequisites.

Step 2: Store credentials in AgentCore Identity

Store your payment provider credentials as a PaymentCredentialProvider. This keeps secrets in AWS Secrets Manager rather than in your application code.

Example

For the complete request and response schema, see CreatePaymentCredentialProvider in the API Reference.

CLI alternative: Store credentials

With the AgentCore CLI, credential storage happens automatically when you add a payment connector (Step 3). Skip this step if you plan to use the CLI path.

Step 3: Create a Payment Manager and Connector

A Payment Manager is the top-level resource that coordinates payment operations. A Payment Connector links the manager to your payment provider credentials. Before creating these resources, set up the required IAM roles as described in IAM roles for AgentCore payments.

Example

AgentCore CLI

The CLI creates the credential provider, Payment Manager, and Payment Connector in one flow. From your AgentCore project directory, add a payment manager and connector together.

Interactive wizard:


agentcore add payment-manager

The wizard prompts for the manager name, pattern (interceptor), auto-payment toggle, and default spend limit. It then asks whether to add a connector and walks through provider selection and credential input.

Non-interactive (Coinbase CDP):


agentcore add payment-manager \
  --name my-payment-manager \
  --auto-payment \
  --default-spend-limit 5.00

agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-coinbase-connector \
  --provider CoinbaseCDP \
  --api-key-id <YOUR_CDP_API_KEY_ID> \
  --api-key-secret <YOUR_CDP_API_KEY_SECRET> \
  --wallet-secret <YOUR_CDP_WALLET_SECRET>

Non-interactive (Privy):


agentcore add payment-manager \
  --name my-payment-manager \
  --auto-payment \
  --default-spend-limit 5.00

agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-privy-connector \
  --provider StripePrivy \
  --app-id <YOUR_PRIVY_APP_ID> \
  --app-secret <YOUR_PRIVY_APP_SECRET> \
  --authorization-id <YOUR_PRIVY_AUTHORIZATION_ID> \
  --authorization-private-key <YOUR_PRIVY_PRIVATE_KEY_BASE64>

After adding, deploy to provision the payment infrastructure:


agentcore deploy

The deploy step creates IAM roles, stores credentials in AgentCore Identity, and provisions the Payment Manager and Connector. You will see "Creating payment infrastructure…" in the output.

AWS CLI

Create the Payment Manager:


aws bedrock-agentcore-control create-payment-manager \
  --name "my-first-payment-manager" \
  --authorizer-type AWS_IAM \
  --role-arn "<YOUR_SERVICE_ROLE_ARN>" \
  --region us-west-2

After the manager reaches READY status, create a credential provider and connector. See Create a Payment Manager and Connector for the full AWS CLI workflow.

AWS SDK

First, create the Payment Manager (the same for both providers):


import time

manager = client.create_payment_manager(
    name="my-first-payment-manager",
    authorizerType="AWS_IAM",
    roleArn="<YOUR_SERVICE_ROLE_ARN>"
)
PAYMENT_MANAGER_ARN = manager["paymentManagerArn"]
print(f"Payment Manager created: {PAYMENT_MANAGER_ARN}")

# Wait for the manager to reach READY state
while True:
    status = client.get_payment_manager(paymentManagerArn=PAYMENT_MANAGER_ARN)
    if status["status"] == "READY":
        break
    print(f"Status: {status['status']}... waiting")
    time.sleep(5)

Then create the Payment Connector for your provider:

Coinbase CDP:


connector = client.create_payment_connector(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    name="my-coinbase-connector",
    paymentConnectorType="CoinbaseCDP",
    credentialProviderArn=CREDENTIAL_PROVIDER_ARN
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(f"Connector created: {PAYMENT_CONNECTOR_ID}")

Privy:


connector = client.create_payment_connector(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    name="my-privy-connector",
    paymentConnectorType="StripePrivy",
    credentialProviderArn=CREDENTIAL_PROVIDER_ARN
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(f"Connector created: {PAYMENT_CONNECTOR_ID}")

If you do not have a service role, see IAM roles for AgentCore payments for instructions on creating one. The console can also create a role on your behalf. For the complete request and response schemas, see CreatePaymentManager and CreatePaymentConnector in the API Reference.

Step 4: Create a payment instrument

A payment instrument is an embedded crypto wallet that your agent uses to pay merchants on behalf of a user. Each instrument is associated with a specific blockchain network.

Example

For the complete request and response schema, see CreatePaymentInstrument in the API Reference.

Fund the wallet and grant permissions

Before the agent can transact, the end user must fund the wallet and grant signing permissions. Open the redirectUrl from the response above in a browser. From the wallet hub, the user can:

Top up the wallet using crypto transfer, credit/debit card, Apple Pay, Google Pay, or ACH
Grant the agent permission to sign transactions on their behalf

For a test environment, fund the wallet with testnet USDC.

After funding, poll the instrument status until it becomes ACTIVE:

Example

For more details on funding flows by provider, see Funding the wallet.

Step 5: Create a payment session

A payment session is a time-bounded context with optional spending limits. When the session expires or the budget is exhausted, the agent cannot make further payments within that session.

Example

Step 6: Process a payment with a Strands agent

With all resources in place, create a Strands agent that handles x402 payments automatically. When the agent calls a paid endpoint and receives an HTTP 402 response, the payments plugin signs the transaction and retries the request.

Example

AgentCore CLI

Invoke your deployed agent with payment context. The CLI passes the payment instrument and session to the agent at runtime, and the agent’s x402 interceptor handles payment automatically.


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id test-user-123

To pass an explicit session instead of auto-creating one:


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --payment-session-id <SESSION_ID> \
  --payment-user-id test-user-123

AWS CLI

Call process-payment directly with an x402 payload (used when you handle payment orchestration yourself):


aws bedrock-agentcore process-payment \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-session-id "$SESSION_ID" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --payment-type "CRYPTO_X402" \
    --payment-input '{
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0xMERCHANT_ADDRESS",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"}
            }
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

For the complete request and response schema, see ProcessPayment in the API Reference.

AWS SDK


from strands import Agent
from strands_tools import http_request
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin

config = AgentCorePaymentsPluginConfig(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    region="us-west-2",
)

plugin = AgentCorePaymentsPlugin(config=config)
agent = Agent(
    system_prompt="You are a helpful assistant that can access paid APIs.",
    tools=[http_request],
    plugins=[plugin],
)

# The agent handles 402 responses automatically
response = agent("Access the premium endpoint at https://example-x402-merchant.com/paid-api")
print(response)

For the complete request and response schema of the underlying API call, see ProcessPayment in the API Reference.

Verify the payment

After the agent processes a payment, check the session to confirm the transaction was recorded:

Example

Troubleshooting

The following issues apply to both the skill-based and manual setup paths.

Issue	Solution
Payment Manager stuck in CREATING	Wait up to 2 minutes. If it moves to CREATE_FAILED, check that your service role ARN and permissions are correct.
"PaymentInstrument not active"	The end user must fund the wallet and grant signing permissions through the redirect URL before the agent can transact.
"Session expired or budget exceeded"	Create a new payment session with a longer expiry or higher spending limit.
"CredentialProvider not found"	Verify the credential provider ARN matches what you created in Step 2. Ensure the region is consistent across all calls.
ProcessPayment returns FAILED	Check that the wallet has sufficient USDC balance for the transaction amount plus gas fees.

Cleanup

Delete the resources you created during this tutorial:

Example

What you’ve built

Through this tutorial, you created:

PaymentCredentialProvider — Payment provider credentials stored in AgentCore Identity
PaymentManager — Top-level resource coordinating payment operations
PaymentConnector — Integration between your manager and the external payment provider
PaymentInstrument — An embedded crypto wallet, funded and authorized by the end user
PaymentSession — A time-bounded, budget-limited payment context
Strands Agent — An AI agent that handles x402 payments automatically

Next steps

Connect to Coinbase x402 Bazaar to discover 10,000+ paid MCP tools.
Integrate with Browser Tool to access paywalled websites.
Enable observability to monitor payment operations in CloudWatch.
Review IAM roles to configure least-privilege access for production.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Core concepts

How it works