https://github.com/hummusonrails/arbitrum-x402-aws
https://github.com/hummusonrails/arbitrum-x402-aws
arbitrum aws aws-lambda cloudfront lambda-edge x402
Last synced: 14 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/hummusonrails/arbitrum-x402-aws
- Owner: hummusonrails
- License: mit
- Created: 2026-04-28T13:37:54.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T17:26:06.000Z (15 days ago)
- Last Synced: 2026-05-28T19:21:12.866Z (15 days ago)
- Topics: arbitrum, aws, aws-lambda, cloudfront, lambda-edge, x402
- Language: TypeScript
- Homepage:
- Size: 396 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
End-to-end x402 payments on Arbitrum One. AWS CloudFront + Lambda@Edge merchant, paid by an AWS Bedrock AgentCore Python agent. USDC settles on Arbitrum One via Coinbase CDP.
## What's in this repo
| App | Path | Language | Role |
|:----|:-----|:---------|:-----|
| Merchant | [`apps/merchant`](apps/merchant/README.md) | TypeScript (pnpm) | Returns HTTP 402, verifies + settles via CDP facilitator, serves gated JSON |
| Agent | [`apps/agent`](apps/agent/README.md) | Python (uv) | Holds embedded wallet via AgentCore, pays on 402, retries with proof |
| `@x402-aws/shared` | [`packages/shared`](packages/shared) | TypeScript (pnpm) | x402 v2 protocol types + Arbitrum constants |
## Architecture
```mermaid
graph LR
subgraph AC[AWS AgentCore]
A[Python Agent
PaymentManager]
W[Embedded Wallet
Coinbase CDP]
A --> W
end
subgraph AWS[AWS us-east-1]
CF[CloudFront]
LE[Lambda Edge
402 Handler]
AG[API Gateway]
OL[Origin Lambda]
end
CDP[CDP Facilitator]
L1[Arbitrum One USDC]
A -->|GET /report| CF
CF -.->|viewer-request| LE
LE -->|verify+settle| CDP
CDP -->|EIP 3009| L1
LE -->|on payment| AG
AG --> OL
classDef aws fill:#FF9900,stroke:#fff,color:#0b1018
classDef arb fill:#12AAFF,stroke:#fff,color:#0b1018
classDef agent fill:#8B5CF6,stroke:#fff,color:#fff
classDef cdp fill:#1652F0,stroke:#fff,color:#fff
class CF,LE,AG,OL,AC aws
class L1 arb
class A,W agent
class CDP cdp
```
## End-to-end flow
```mermaid
sequenceDiagram
autonumber
participant A as Python Agent
participant ACore as AgentCore
PaymentManager
participant CF as CloudFront
participant LE as Lambda Edge
participant CDP as CDP Facilitator
participant L1 as Arbitrum One
A->>CF: GET /report
CF->>LE: viewer-request
LE-->>A: 402 + accepts[]
A->>ACore: generate_payment_header(402 body)
Note over ACore: Check session budget,
sign via embedded wallet
ACore-->>A: X-PAYMENT header
A->>CF: GET /report (X-PAYMENT)
CF->>LE: viewer-request
LE->>CDP: verify + settle
CDP->>L1: transferWithAuthorization
L1-->>CDP: tx hash
CDP-->>LE: success + txHash
LE-->>A: 200 + gated JSON + Arbiscan link
```
Featured on X · The narrative behind this synthesis of x402, Arbitrum, and AWS →
## Quick Start
```bash
# 1. Install both stacks
make install
# 2. Configure
cp .env.example .env
$EDITOR .env # set RECIPIENT_ADDRESS, AGENTCORE_*, etc.
# 3. Print CDP env for the merchant
pnpm --filter @x402-aws/merchant print-cdp-env /path/to/cdp_api_key.json
# Paste the printed lines into .env
# 4. Bootstrap CDK
pnpm --filter @x402-aws/merchant exec cdk bootstrap aws://$ACCOUNT_ID/us-east-1
# 5. Deploy the merchant
make deploy-merchant
# 6. Set RESOURCE_URL in .env from the merchant's DistributionDomainName output
# 7. Bootstrap the agent (creates AgentCore resources, prompts you to fund the wallet)
make setup-agent
# 8. Paste the printed PAYMENT_* IDs into .env
# 9. Run the agent
make run-agent
```
## Makefile
| Target | What it does |
|:-------|:-------------|
| `make install` | `pnpm install` + `uv sync` |
| `make test` | All tests across both stacks |
| `make synth` | CDK synth for the merchant |
| `make deploy-merchant` | CDK deploy |
| `make destroy-merchant` | CDK destroy |
| `make setup-agent` | Bootstrap AgentCore resources (one-time) |
| `make run-agent` | Run the agent against the merchant |
| `make teardown-agent` | Delete AgentCore resources |
| `make clean` | Remove all build artifacts and venvs |
## Tests
```bash
make test
```
26 tests: 17 in the merchant (vitest), 2 in `@x402-aws/shared` (vitest), 7 in the agent (pytest).
## Stack
| Layer | Tool |
|:------|:-----|
| Workspace | pnpm 9+ (apps/merchant, packages/*) + uv (apps/agent) + root Makefile |
| Merchant IaC | AWS CDK 2 (TypeScript) |
| CDN / edge | CloudFront + Lambda@Edge (Node 20, x86_64) |
| Origin | API Gateway HTTP API + Lambda (Node 20, ARM) |
| Settlement | CDP x402 facilitator |
| Agent runtime | Python 3.10+, `boto3`, `bedrock-agentcore[strands-agents]`, `httpx` |
| Wallet | AgentCore embedded wallet, Coinbase CDP |
| Chain | Arbitrum One (CAIP-2 `eip155:42161`) |
| Asset | Native USDC (`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`) |
## Contributing
PRs welcome. Open an issue first for anything non-trivial.
## License
MIT. See [LICENSE](LICENSE).