AWS Builder Center
Weekend Showcase Challenge: x402 Weather Agent (On Amazon Bedrock AgentCore payments)

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?

Engineer, AWS Community Builder 2026 「AI Engineering」

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_weather
get_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:
  1. 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 the  ResourceRetrievalRole  trust policy pinned  aws:SourceArn  to the wrong region and  CreatePaymentManager  failed with "Role validation failed … its trust policy allows assumption by this service." Fix: pin the whole app to  us-west-2 .
  1. 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").
  1. Stripe Privy has no hosted funding page. Coinbase returns a  redirectUrl  to 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).
  1. x402 v2 header name.  @x402/core  v2's server reads only the  PAYMENT-SIGNATURE  header. My client was sending the (correctly v2-encoded) proof in the v1  X-PAYMENT  header, so the server saw "no payment" and returned an empty  402 {}  with no error. One-line fix, hours to find — I ended up decoding the  payment-required  response header to surface the real reason.
  1. Session expiry.  ProcessPayment  returns "Your session has expired" once the Payment Session's  expiryTimeInMinutes  elapses. Re-run  new-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  ProcessPayment  data-plane call that produces the x402 proof.
  • AWS IAM — a four-role separation model (ControlPlane / Management / ProcessPayment / ResourceRetrieval) with an explicit  Deny  on  ProcessPayment  for the role that can create sessions.
  • AWS CloudFormation via AWS CDK (TypeScript) —  FoundationStack  is deployed to  us-west-2  and provisions the roles plus an Amazon VPC, an Amazon ECS cluster, and an AWS Secrets Manager secret for the facilitator's gas key.  cdk-nag  runs 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 
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article