
Weekend Showcase Challenge: x402 Weather Agent (On Amazon Bedrock AgentCore payments)
Agents can already call APIs. What they cannot do well yet is *pay* for them. Most paid APIs assume a human with a credit card and a dashboard. The [x402 protocol](https://www.x402.org/) fixes the transport side: a server answers `HTTP 402 Payment Required` with machine-readable payment terms, the client pays, and retries. But that still leaves the hard part: where does the money come from, who is allowed to spend it, and how do you stop a looping agent from draining a wallet?
Vision: give an AI agent its own wallet, safely
Agents can already call APIs. What they cannot do well yet is pay for them. Most
paid APIs assume a human with a credit card and a dashboard. The
x402 protocol fixes the transport side: a server answers
HTTP 402 Payment Required with machine-readable payment terms, the client pays,
and retries. But that still leaves the hard part: where does the money come from,
who is allowed to spend it, and how do you stop a looping agent from draining a
wallet?x402 Weather Agent is an end-to-end proof that Amazon Bedrock AgentCore
Payments answers that hard part. An MCP tool (
get_weather ) is called by Claude
inside Claude Code. Behind the tool sits a paywalled weather API priced at
$0.01 per call in USDC on Base Sepolia. When the agent hits the paywall, the
tool asks AgentCore Payments to produce a signed payment, retries, and returns the
weather — and the model never sees a private key, a signed proof, or the raw
payment header.The spend controls are enforced by AWS, not by my code: a Payment Session
carries a budget and an expiry, and the runtime role can only call
ProcessPayment — it cannot create sessions or raise budgets. "Who can set a
budget" and "who can spend it" are split at the IAM level.

What it does
The repo is a pnpm monorepo with four independently runnable pieces: an x402
resource server (Hono), an x402 facilitator (Hono + viem, submits the
on-chain settlement), an MCP server exposing the paid API as a tool, and an
AWS CDK app that provisions the AWS side.
Here is a real run of the tool (via the included
pnpm --filter mcp call test client):利用可能なツール: get_weatherget_weather を呼び出します(city: Tokyo)...結果: {"city":"Tokyo","weather":"sunny","temperature":70, "payment":{"settled":true,"processPaymentId":"5edf3cb3-965d-4f30-9db5-d1da5284ae26"}}payment.settled: true means the full path ran: MCP → 402 → AgentCore
ProcessPayment → PAYMENT-SIGNATURE retry → facilitator settlement of USDC on
Base Sepolia → weather returned.How I built it
The build is small; the interesting work was getting the AWS + wallet plumbing
right. Five things cost me real time, and none of them are in the quickstart docs:
- Region. AgentCore Payments is only in
us-east-1 / us-west-2 / eu-central-1 / ap-southeast-2. I deployed my CDK stack to Tokyo first, so theResourceRetrievalRoletrust policy pinnedaws:SourceArnto the wrong region andCreatePaymentManagerfailed with "Role validation failed … its trust policy allows assumption by this service." Fix: pin the whole app tous-west-2.
- Bring-your-own service role. When you pass your own role ARN to
CreatePaymentManager, AWS does not auto-attach the base permissions — that only happens for console-created roles. The error is "The execution role is missing the required permission: bedrock-agentcore:CreateWorkloadIdentity." Fix: attach the workload-identity / payment-token / secrets permissions in CDK yourself (they are documented under "Using an existing role").
- Stripe Privy has no hosted funding page. Coinbase returns a
redirectUrlto a hosted WalletHub; Privy does not. You self-host the Privy reference frontend, log in as the end user, fund from the Circle faucet, and click "Connect agent" to register the agent key as a session signer (delegation).
- x402 v2 header name.
@x402/corev2's server reads only thePAYMENT-SIGNATUREheader. My client was sending the (correctly v2-encoded) proof in the v1X-PAYMENTheader, so the server saw "no payment" and returned an empty402 {}with no error. One-line fix, hours to find — I ended up decoding thepayment-requiredresponse header to surface the real reason.
- Session expiry.
ProcessPaymentreturns "Your session has expired" once the Payment Session'sexpiryTimeInMinuteselapses. Re-runnew-session, update the env var, done. This is a feature, not a bug — short-lived budgets.
An admin CLI (
agentcore-payments-admin.ts ) drives the control-plane setup
(credential provider → payment manager → connector → instrument → session) and is
deliberately TTY-gated: session creation requires typing approve , so CI or an
agent can never mint itself a budget.AWS services used
- Amazon Bedrock AgentCore Payments — Payment Manager, Payment Connector,
Payment Credential Provider (Stripe Privy), Payment Instrument (embedded wallet),
Payment Session, and the
ProcessPaymentdata-plane call that produces the x402 proof.
- AWS IAM — a four-role separation model (ControlPlane / Management /
ProcessPayment / ResourceRetrieval) with an explicit
DenyonProcessPaymentfor the role that can create sessions.
- AWS CloudFormation via AWS CDK (TypeScript) —
FoundationStackis deployed tous-west-2and provisions the roles plus an Amazon VPC, an Amazon ECS cluster, and an AWS Secrets Manager secret for the facilitator's gas key.cdk-nagruns on every synth.
- Optional Amazon ECS on AWS Fargate + ALB stacks are included to host the resource server / facilitator / MCP server.
Architecture overview
The AWS-hosted layer is IAM + AgentCore Payments (the trust boundary and the
budget engine) plus the CDK-managed VPC/ECS/Secrets foundation. The x402 services
run locally against that AWS layer during development, or on the included Fargate
stacks. Base Sepolia is the settlement chain; USDC is the asset.
What I learned this summer
The theme of the Summer Build Series was "an agent that runs on its own." The
lesson from adding payments to that: autonomy and spend authority have to be
separated by the platform, not by prompt engineering. AgentCore Payments does this
cleanly — the agent gets a capability (
ProcessPayment within a session), not a
wallet. I also re-learned that the last 10% of an integration (region, trust
policies, header names, delegation) is where all the time goes, and that surfacing
the real upstream error early is worth more than any amount of guessing.If you're trying AgentCore Payments, the five gotchas above and the full
docs/design.md in the repo should save you a weekend.Links
- Design doc:
docs/design.md· Setup + demo:README.md
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article