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.

You can provide credentials in two ways when you create a Coinbase connector. With Quick create (recommended), you authorize through Coinbase and AgentCore payments provisions and stores the credentials for you — no keys to generate or paste. With Manual, you supply Coinbase API keys that you generated yourself. Stripe (Privy) uses the manual flow only. With Quick create, you skip Steps 1 and 2 of the manual setup.

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 — See Supported AWS Regions.
A Coinbase AWS Marketplace subscription (Coinbase only) — If you use Coinbase as your payment provider, you must subscribe to the Coinbase Wallets for AgentCore Payments listing in AWS Marketplace. With this subscription, your Coinbase wallet usage charges are consolidated into your monthly AWS bill based on Coinbase’s pricing on the Coinbase website. See Subscribe to Coinbase Wallets for AgentCore Payments in AWS Marketplace.
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 add a payment connector. For Coinbase with Quick create (recommended), you authorize through Coinbase and AgentCore payments provisions the credentials for you — no secrets to enter. For Coinbase manual or Stripe (Privy), you run agentcore add payment-connector to enter your provider secrets.
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

If you use the manual flow (Coinbase manual or Stripe Privy), obtain credentials from your provider before adding the connector. With Coinbase Quick create, you skip this — you authorize through Coinbase instead of pasting keys.

Coinbase CDP (manual only) — API Key ID, API Key Secret, and Wallet Secret from the Coinbase Developer Platform website (with Delegated signing enabled). Coinbase also requires an active AWS Marketplace subscription to the Coinbase Wallets for AgentCore Payments listing. See Subscribe to Coinbase Wallets for AgentCore Payments in AWS Marketplace.
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
A Coinbase AWS Marketplace subscription (Coinbase only) — If you use Coinbase as your payment provider, you must subscribe to the Coinbase Wallets for AgentCore Payments listing in AWS Marketplace. With this subscription, your Coinbase wallet usage charges are consolidated into your monthly AWS bill based on Coinbase’s pricing on the Coinbase website. See Subscribe to Coinbase Wallets for AgentCore Payments in AWS Marketplace.
An AWS Region where AgentCore payments is available — 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 (manual flow)

Steps 1 and 2 apply to the manual credential flow — Coinbase (manual) or Stripe (Privy).

Note

Using Quick create for Coinbase (recommended). Skip Steps 1 and 2 and see Step 3. AgentCore payments provisions the Coinbase credentials for you after you authorize through Coinbase — you do not obtain or store any keys.

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 log in to your account. Select a project.
Navigate to your API Keys dashboard, choose Create secret API Key, and note the API Key ID and API Key Secret. Go back to your project.
Under Products > Wallets > Non-custodial Wallet > Security, choose Generate new under Generate Wallet secret and note the Wallet Secret.
Under Products > Wallets > Non-custodial Wallet > Security, enable Delegated signing.

You will use these 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.

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 from the P-256 key pair

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

Step 2: Store credentials in AgentCore Identity (manual flow)

Store your payment provider credentials as a PaymentCredentialProvider. This keeps secrets in AWS Secrets Manager rather than in your application code. If you are using Coinbase Quick create, skip this step. AgentCore payments creates and stores the credential provider for you in Step 3.

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.

First, create the Payment Manager (common to all providers):

Example

Console

Open the Amazon Bedrock AgentCore console.
In the navigation pane, under Build, choose Payments.
Choose Create Payment Manager, enter a Name, and under Permissions choose Create and use a new service role (or select an existing role).
Under Inbound Auth, choose Use IAM username.
Choose Create Payment Manager. You add the connector in the provider section below.

For the full console walkthrough including JWT authorization and custom claims, see Create a Payment Manager and Connector.

AgentCore CLI


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

Add the connector in the provider section below, then run agentcore deploy.

AgentCore SDK


from bedrock_agentcore.payments.client import PaymentClient

payment_client = PaymentClient(region_name="us-west-2")

manager = payment_client.create_payment_manager(
    name="my-first-payment-manager",
    authorizer_type="AWS_IAM",
    role_arn="<YOUR_SERVICE_ROLE_ARN>",
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]

Use PAYMENT_MANAGER_ID with payment_client to create the connector in the provider section below.

AWS CLI


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

Wait for the manager to reach READY, then create the connector in the provider section below.

AWS SDK


import time

manager = client.create_payment_manager(
    name="my-first-payment-manager",
    authorizerType="AWS_IAM",
    roleArn="<YOUR_SERVICE_ROLE_ARN>"
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]

while client.get_payment_manager(paymentManagerId=PAYMENT_MANAGER_ID)["status"] != "READY":
    time.sleep(5)

Then create a Payment Connector for your provider. Choose the Coinbase section (Quick create or Manual) or the Stripe (Privy) section.

Coinbase — Quick create (recommended)

With Quick create, you do not obtain or store Coinbase credentials. In the console, you complete this by choosing Quick Create with Coinbase. With the AWS CLI, AWS SDK, AgentCore CLI, or AgentCore SDK, pass provisionMode=QUICK_CREATE with an empty credential list. The connector starts in PENDING_AUTHENTICATION and returns an authorizationUrl. You open the returned authorizationUrl in a browser. After you authorize through Coinbase, AgentCore payments provisions the credentials and moves the connector to READY.

Example

Console

In the Payment connector section, choose Add outbound auth > Create payment auth, and for Payment provider choose Coinbase.
Choose Quick create configurations - recommended, then choose Create payment auth.
A Coinbase window opens — sign in or sign up and authorize (link) your Coinbase CDP account.
AgentCore payments provisions the Coinbase CDP API key and Wallet secret and stores them for you. The connector moves from PENDING_AUTHENTICATION to READY.

AgentCore CLI


agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-coinbase-connector \
  --provider CoinbaseCDP \
  --quick-create

agentcore deploy

The CLI opens the Coinbase authorization flow. After you authorize, the service provisions the credentials and the connector reaches READY.

AgentCore SDK


connector = payment_client.create_payment_connector(
    payment_manager_id=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    connector_type="CoinbaseCDP",
    credential_provider_configurations=[],
    provision_mode="QUICK_CREATE",
)
# Open connector["authorizationUrl"], authorize through Coinbase,
# then poll get_payment_connector until status == "READY".

AWS CLI


aws bedrock-agentcore-control create-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --name "my-coinbase-connector" \
  --type CoinbaseCDP \
  --credential-provider-configurations '[]' \
  --provision-mode QUICK_CREATE \
  --region us-west-2

The response includes status: PENDING_AUTHENTICATION and an authorizationUrl. Open the URL in a browser and complete the Coinbase authorization, then poll until the connector is READY:


aws bedrock-agentcore-control get-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --payment-connector-id "<PAYMENT_CONNECTOR_ID>" \
  --region us-west-2

AWS SDK


connector = client.create_payment_connector(
    paymentManagerId=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    type="CoinbaseCDP",
    credentialProviderConfigurations=[],
    provisionMode="QUICK_CREATE",
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(connector["status"], connector.get("authorizationUrl"))
# PENDING_AUTHENTICATION  https://...
# Open the authorizationUrl, authorize, then poll get_payment_connector until READY.

Coinbase — Manual

Use Coinbase CDP credentials that you generated yourself (Steps 1–2). Create the credential provider, then create the connector referencing its ARN. For the Console or AgentCore CLI manual walkthrough, see Create a Payment Manager and Connector.

Example

Stripe (Privy) — Manual

Stripe (Privy) uses the manual flow only. Create the credential provider from your Privy credentials (Steps 1–2), then create the connector referencing its ARN. For the Console or AgentCore CLI manual walkthrough, see Create a Payment Manager and Connector.

Example

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 Amazon Bedrock AgentCore Control 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

AgentCore SDK


from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

instrument = manager.create_payment_instrument(
    user_id="test-user-123",
    payment_connector_id=PAYMENT_CONNECTOR_ID,
    payment_instrument_type="EMBEDDED_CRYPTO_WALLET",
    payment_instrument_details={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    },
)
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

AWS CLI


aws bedrock-agentcore create-payment-instrument \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --user-id "test-user-123" \
    --payment-instrument-type "EMBEDDED_CRYPTO_WALLET" \
    --payment-instrument-details '{
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

Save the paymentInstrumentId and redirectUrl from the response.

AWS SDK


import uuid

dp_client = boto3.client("bedrock-agentcore", region_name="us-west-2",
    endpoint_url="https://bedrock-agentcore.us-west-2.amazonaws.com")

instrument = dp_client.create_payment_instrument(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID,
    paymentInstrumentType="EMBEDDED_CRYPTO_WALLET",
    paymentInstrumentDetails={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    },
    clientToken=str(uuid.uuid4()),
)
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

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

AgentCore CLI

When using the CLI, you do not need to create a session manually. Pass --auto-session to agentcore invoke and the CLI creates or reuses a session with the default spend limit you configured on the payment manager.


agentcore invoke \
  --prompt "your prompt here" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id test-user-123

To use a specific session you created through the SDK, pass --payment-session-id instead of --auto-session.

AgentCore SDK


from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

session = manager.create_payment_session(
    user_id="test-user-123",
    limits={"maxSpendAmount": {"value": "5.00", "currency": "USD"}},
    expiry_time_in_minutes=60
)
SESSION_ID = session["paymentSessionId"]
print(f"Session created: {SESSION_ID} (expires in 60 minutes, $5.00 limit)")

AWS CLI


aws bedrock-agentcore create-payment-session \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --user-id "test-user-123" \
    --expiry-time-in-minutes 60 \
    --limits '{"maxSpendAmount": {"value": "5.00", "currency": "USD"}}' \
    --client-token "$(uuidgen)" \
    --region us-west-2

AWS SDK


session = dp_client.create_payment_session(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    expiryTimeInMinutes=60,
    limits={"maxSpendAmount": {"value": "5.00", "currency": "USD"}},
    clientToken=str(uuid.uuid4()),
)
SESSION_ID = session["paymentSessionId"]
print(f"Session created: {SESSION_ID} (expires in 60 minutes, $5.00 limit)")

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

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

AgentCore SDK

Use the PaymentManager class to generate payment headers when you receive an HTTP 402 response:


import uuid
from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

# When you receive a 402 response, generate payment proof
payment_required_request = {
    "statusCode": 402,
    "headers": payment_required["headers"],
    "body": payment_required["body"],
}
payment_proof_headers = manager.generate_payment_header(
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    payment_required_request=payment_required_request,
    client_token=str(uuid.uuid4()),
)

payment_proof_headers contains the payment proof header. Include this header when retrying the request to the paid endpoint.

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