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, Amazon SDK, or Amazon 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:

Amazon Account with credentials configured (aws configure)
An Amazon Region where AgentCore payments is available — See Supported Amazon Regions.
A Coinbase Amazon Marketplace subscription (Coinbase only) — If you use Coinbase as your payment provider, you must subscribe to the Coinbase Wallets for AgentCore Payments listing in Amazon Marketplace. With this subscription, your Coinbase wallet usage charges are consolidated into your monthly Amazon bill based on Coinbase’s pricing on the Coinbase website. See Subscribe to Coinbase Wallets for AgentCore Payments in Amazon Marketplace.
Node.js 20.12 or later 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 Amazon 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 Amazon. 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.
Deploys resources to your Amazon account (agentcore deploy)
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 step. You authorize through Coinbase instead of entering API keys manually.

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 Amazon Marketplace subscription to the Coinbase Wallets for AgentCore Payments listing. See Subscribe to Coinbase Wallets for AgentCore Payments in Amazon 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, Amazon CLI, or Amazon SDK (Boto3).

Prerequisites

Before starting, make sure you have:

Amazon Account with credentials configured (aws configure)
Python 3.10+ installed
A Coinbase Amazon Marketplace subscription (Coinbase only) — If you use Coinbase as your payment provider, you must subscribe to the Coinbase Wallets for AgentCore Payments listing in Amazon Marketplace. With this subscription, your Coinbase wallet usage charges are consolidated into your monthly Amazon bill based on Coinbase’s pricing on the Coinbase website. See Subscribe to Coinbase Wallets for AgentCore Payments in Amazon Marketplace.
An Amazon Region where AgentCore payments is available — See Supported Amazon 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 installed (npm install -g @aws/agentcore), you can use it in Steps 3 and 6 and in the cleanup section. To look up payment resources, use agentcore payment instrument get and agentcore payment session get.

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 Amazon 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, you add the credential provider with agentcore add credentials payment in the manual connector sections of 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 Connections, 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

If you don’t have an AgentCore CLI project, install the CLI and create a project with a Runtime for Step 6. The Runtime must allow the two payment headers that Step 6 sends. For details, see Pass custom headers to Amazon Bedrock AgentCore Runtime:


npm install -g @aws/agentcore
agentcore create --name PaymentsQuickstart --template empty
cd PaymentsQuickstart
agentcore add runtime \
  --name MyRuntime \
  --language python \
  --protocol HTTP \
  --request-header-allowlist X-Amzn-Bedrock-AgentCore-Runtime-Custom-Payment-Session-Id X-Amzn-Bedrock-AgentCore-Runtime-Custom-Payment-Instrument-Id
cd app/MyRuntime
uv init --bare
uv add \
  "aws-opentelemetry-distro~=0.21.0" \
  "bedrock-agentcore[strands-agents]>=1.18.1,<2" \
  "botocore[crt]~=1.43.0" \
  "strands-agents>=1.15,<2"
cd ../..

The add runtime command creates the Runtime documentation but doesn’t generate application code. Before your first deployment, save the Runtime entrypoint from Step 6 as app/MyRuntime/main.py. Then add the Payment Manager:


agentcore add payment-manager \
  --name MyPaymentManager \
  --default-spend-limit 5.00

Add the connector in the provider section below, then run agentcore deploy. After the deployment, run agentcore status --json. Use the payment-manager arn as PAYMENT_MANAGER_ARN and the id of the payment-connector under its children as PAYMENT_CONNECTOR_ID in Steps 4 and 5.

AgentCore SDK


from bedrock_agentcore.payments.client import PaymentClient

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

manager = payment_client.create_payment_manager(
    name="MyPaymentManager",
    authorizer_type="AWS_IAM",
    role_arn="<YOUR_SERVICE_ROLE_ARN>",
    wait_for_ready=True,
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]
PAYMENT_MANAGER_ARN = manager["paymentManagerArn"]

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

Amazon CLI


aws bedrock-agentcore-control create-payment-manager \
  --name "MyPaymentManager" \
  --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.

Amazon SDK


import time

manager = client.create_payment_manager(
    name="MyPaymentManager",
    authorizerType="AWS_IAM",
    roleArn="<YOUR_SERVICE_ROLE_ARN>"
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]
PAYMENT_MANAGER_ARN = manager["paymentManagerArn"]

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 Amazon CLI, Amazon 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 MyPaymentManager \
  --name my_coinbase_connector \
  --quick-create

agentcore deploy

agentcore deploy prints Authorize payment connector "<name>": <url>. Open the URL in a browser and authorize through Coinbase. The service then 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",
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
# Open connector["authorizationUrl"], authorize through Coinbase,
# then poll get_payment_connector until status == "READY".

Amazon 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

Amazon 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"]["embeddedCryptoWallet"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

Amazon 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 paymentInstrument.paymentInstrumentId and paymentInstrument.paymentInstrumentDetails.embeddedCryptoWallet.redirectUrl from the response.

Amazon SDK


import uuid

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

response = 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 = response["paymentInstrument"]
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["embeddedCryptoWallet"]["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

Save the returned payment session ID. In the next step, pass this ID and the payment instrument ID from Step 4 when invoking your agent.

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

Update your Python agent with AgentCorePaymentsPlugin using the AgentCore SDK example in this step. Deploy the updated agent from your project directory:


agentcore deploy

In the entrypoint, replace os.environ["PAYMENT_MANAGER_ARN"] with os.environ["AGENTCORE_PAYMENT_MYPAYMENTMANAGER_MANAGER_ARN"]. agentcore deploy sets this variable on the Python HTTP Runtimes in the project and grants their execution roles payment access to the manager.

Set SESSION_ID and INSTRUMENT_ID to the IDs from the preceding steps. Invoke the agent with these values as request headers. The Runtime passes the headers to the agent only if its request header allowlist includes them, as set up in Step 3. Replace MyRuntime with your project’s Runtime name.


agentcore invoke --runtime MyRuntime \
    --payload '{"prompt":"Access the premium endpoint at https://example-x402-merchant.com/paid-api"}' \
    --header "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Payment-Session-Id: $SESSION_ID" \
    --header "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Payment-Instrument-Id: $INSTRUMENT_ID"

These are application-defined headers. The entrypoint in the AgentCore SDK example reads them and supplies their values to the payment plugin. The CLI’s --session-id option identifies a Runtime session, not a payment session.

AgentCore SDK

Add bedrock-agentcore[strands-agents] to your agent’s dependencies. If you don’t deploy the Runtime with the AgentCore CLI, set PAYMENT_MANAGER_ARN in the Runtime’s environment to the manager ARN from Step 3, and make sure that its execution role can access that manager. The Runtime must also allow the two payment headers in its request header allowlist. This IAM example uses test-user-123, the payment user from the preceding steps.

The following Runtime entrypoint reads the payment headers and configures a Strands agent for each request. The plugin provides the HTTP request tool and handles its x402 responses.


import os

from strands import Agent
from bedrock_agentcore.payments.integrations.strands import (
    AgentCorePaymentsPlugin,
    AgentCorePaymentsPluginConfig,
)
from bedrock_agentcore.runtime import BedrockAgentCoreApp, RequestContext

app = BedrockAgentCoreApp()
HEADER_PREFIX = "x-amzn-bedrock-agentcore-runtime-custom-"


@app.entrypoint
def invoke(payload: dict, context: RequestContext) -> dict:
    headers = {
        key.lower(): value
        for key, value in (context.request_headers or {}).items()
    }
    session_id = headers.get(HEADER_PREFIX + "payment-session-id", "").strip()
    instrument_id = headers.get(HEADER_PREFIX + "payment-instrument-id", "").strip()
    if not session_id or not instrument_id:
        raise ValueError("Payment session and instrument headers are required.")

    config = AgentCorePaymentsPluginConfig(
        payment_manager_arn=os.environ["PAYMENT_MANAGER_ARN"],
        user_id="test-user-123",
        payment_session_id=session_id,
        payment_instrument_id=instrument_id,
        region="us-west-2",
        payment_tool_allowlist=["http_request"],
    )
    agent = Agent(plugins=[AgentCorePaymentsPlugin(config=config)])
    return {"result": str(agent(payload["prompt"]))}


if __name__ == "__main__":
    app.run()

For standalone Strands agents and payment-error handling, see Strands Agents. To handle payment proof and retries yourself, see Process a payment.

Amazon 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.

Amazon SDK

If your application handles the merchant’s HTTP 402 response directly, call process_payment with its payment requirements. Replace the example requirements below with those returned by the merchant.


import uuid

payment = dp_client.process_payment(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID,
    paymentInstrumentId=INSTRUMENT_ID,
    paymentType="CRYPTO_X402",
    paymentInput={
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0xMERCHANT_ADDRESS",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"},
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)
print(payment["paymentOutput"])

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

AgentCore SDK


session = manager.get_payment_session(
    user_id="test-user-123",
    payment_session_id=SESSION_ID
)
available = session["availableLimits"]["availableSpendAmount"]
print(f"Remaining: {available['value']} {available['currency']}")

You can also check the instrument balance:


balance = manager.get_payment_instrument_balance(
    user_id="test-user-123",
    payment_connector_id=PAYMENT_CONNECTOR_ID,
    payment_instrument_id=INSTRUMENT_ID,
    chain="BASE_SEPOLIA",
    token="USDC",
)
token_balance = balance["tokenBalance"]
print(f"Wallet balance: {token_balance['amount']} {token_balance['token']}")

Amazon CLI


aws bedrock-agentcore get-payment-session \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-session-id "$SESSION_ID" \
    --region us-west-2

aws bedrock-agentcore get-payment-instrument-balance \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --user-id "test-user-123" \
    --chain BASE_SEPOLIA \
    --token USDC \
    --region us-west-2

Amazon SDK


from decimal import Decimal

session = dp_client.get_payment_session(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID
)["paymentSession"]
limit = session["limits"]["maxSpendAmount"]
available = session["availableLimits"]["availableSpendAmount"]
spent = Decimal(limit["value"]) - Decimal(available["value"])
print(f"Amount spent: {spent} {limit['currency']}")

You can also check the instrument balance:


balance = dp_client.get_payment_instrument_balance(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID,
    paymentInstrumentId=INSTRUMENT_ID,
    chain="BASE_SEPOLIA",
    token="USDC",
)
token_balance = balance["tokenBalance"]
print(f"Wallet balance: {token_balance['amount']} {token_balance['token']}")

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

AgentCore CLI


agentcore remove payment-manager --name MyPaymentManager
agentcore remove credential --name my_coinbase_credentials
agentcore deploy

Removing the payment manager also removes its connectors. If you used the manual flow, remove the credential you added in Step 3 (my_coinbase_credentials or my_privy_credentials). Quick create adds no credential to your project, so skip that command. The remove commands update the local configuration. The follow-up deploy tears down the payment infrastructure in your account.

AgentCore SDK


from bedrock_agentcore.payments.client import PaymentClient

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

payment_client.delete_payment_manager(
    payment_manager_id="<paymentManagerId>"
)

print("Payment Manager deleted.")

Amazon CLI


aws bedrock-agentcore delete-payment-instrument \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --region us-west-2

aws bedrock-agentcore-control delete-payment-connector \
    --payment-manager-id "$PAYMENT_MANAGER_ID" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --region us-west-2

aws bedrock-agentcore-control delete-payment-manager \
    --payment-manager-id "$PAYMENT_MANAGER_ID" \
    --region us-west-2

# Manual flow only: delete the credential provider from Step 2 (my-privy-credentials for Privy)
aws bedrock-agentcore-control delete-payment-credential-provider \
    --name "my-coinbase-credentials" \
    --region us-west-2

Amazon SDK


# Delete payment instrument
dp_client.delete_payment_instrument(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID,
    paymentInstrumentId=INSTRUMENT_ID
)

# Delete payment connector
client.delete_payment_connector(
    paymentManagerId=PAYMENT_MANAGER_ID,
    paymentConnectorId=PAYMENT_CONNECTOR_ID
)

# Delete payment manager
client.delete_payment_manager(
    paymentManagerId=PAYMENT_MANAGER_ID
)

# Manual flow only: delete the credential provider from Step 2 (my-privy-credentials for Privy)
client.delete_payment_credential_provider(name="my-coinbase-credentials")

print("All payment resources deleted.")

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.

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.

Core concepts

How it works