Prerequisites Step 1: Obtain payment provider credentials Step 2: Store credentials in AgentCore Identity Step 3: Create a Payment Manager and Connector Step 4: Create a payment instrument Step 5: Create a payment session Step 6: Process a payment with a Strands agent Verify the payment 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.

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

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.

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.

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

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.

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

Verify the payment

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

Example

Troubleshooting

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.

Document Conventions

Core concepts

How it works