straitsX-mcp-demo

Your AI agent pays with crypto and gets a single-use virtual Visa card back.

This repo is the StraitsX Phase-3 reference stack for the SMU hackathon: an agent-side card gateway (pure x402 client — signs EIP-3009 transferWithAuthorization for XSGD on Avalanche Fuji), a demo store to spend the card at, a conformance suite, and a flagship shopping agent example. Everything talks to the real StraitsX sandbox from the first minute — no simulators, no rebuild for event day.

• Participant guide: docs/PARTICIPANT_GUIDE.md · event-day runbook: docs/EVENT_DAY.md

1. Quickstart (under 10 minutes)

git clone <this repo> && cd straitsX-mcp-demo
npm install
npm run setup      # copies .env, generates your agent key, prints the ADDRESS only

Send that address to the organizers — they fund it with Fuji XSGD (and whitelist it if the event requires it). While you wait:

npm run stack      # demo store :4030 + gateway :4010 (issuer = live StraitsX sandbox)
npm run doctor     # green/red health table: env, live SSE MCP, unpaid cardapi 402 probe, RPC, XSGD balance

Then plug in your agent (next section) and issue your first card against the real sandbox:

npx tsx examples/shopping-agent/index.ts --scripted   # no LLM key needed

Unfunded wallet? The scripted agent automatically runs the safe dry run (discovery → 402 decode → EIP-3009 signing, paid POST never sent) and prints how to get funded. Once the wallet holds XSGD, the same command issues a real card.

Amounts are human token units everywhere participants type them: 12 means 12.00 SGD (sandbox) or 12.00 USD (prod). The gateway signs the exact atomic amount quoted by the live 402 challenge — never a number computed client-side.

2. Zero-config agent hookup (.mcp.json)

The repo root ships a committed .mcp.json registering the card gateway as a stdio MCP server. Claude Code picks it up automatically when you open the repo — approve the server when prompted and you have the tools get_virtual_card, get_wallet_status, approve_payment / reject_payment.

Ask: "Use get_virtual_card to issue me a 12 SGD card as cardholder 'Team Rocket', then give me the settlement transaction link."

3. Connect any other client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "card-gateway": {
      "command": "npx",
      "args": ["tsx", "/ABSOLUTE/PATH/TO/straitsX-mcp-demo/packages/card-gateway/bin/gateway.ts", "--stdio"]
    }
  }
}

Cursor (.cursor/mcp.json): same shape as the repo-root .mcp.json — copy it verbatim.

OpenAI Agents SDK / LangGraph / anything HTTP — skip MCP entirely and use the gateway REST surface (npm run stack exposes it on :4010):

curl -X POST http://127.0.0.1:4010/card \
  -H 'content-type: application/json' \
  -d '{"amount": 12, "cardholder_name": "Team Rocket"}'

In an OpenAI Agents SDK / LangGraph tool, that curl is your tool body: one POST, JSON in (amount, cardholder_name), JSON out (card_opaque_id, settlement_tx, view URL). The gateway holds your key; the model never sees it.

Raw wire (curl only, no gateway): examples/curl/walkthrough.md walks the whole x402 exchange by hand — probe, 402 decode, EIP-3009 sign, paid POST, settlement header, idempotent replay.

4. Profiles

NETWORK_PROFILE in .env selects a checked-in profile from profiles/. Secrets never live in profiles — only in your gitignored .env. Default: sandbox-live.

Profile	Card issuer	Settlement	Who pays gas	Use when
sandbox-live	LIVE StraitsX sandbox	REAL Fuji XSGD, you sign x402	StraitsX relayer	hackathon main track (default)
event-prod	LIVE StraitsX prod	USDC on Base, custodial	StraitsX	real cards (passphrase)

5. Sandbox vs Production (the live StraitsX endpoints)

Sandbox — Fuji XSGD, you sign x402 (NETWORK_PROFILE=sandbox-live, the default):

• MCP: https://card.straitsx.ai/sandbox/sse (SSE transport)
• Tools: get_card_sandbox { wallet_address, cardholder_name, amount_sgd (5–30) }, view_card_sandbox { card_opaque_id, settlement_tx, wallet_address } → fresh one-time iframe URL
• Card API (discovered via MCP): POST https://card.straitsx.ai/sandbox/cardapi/issue_card — unpaid returns HTTP 402 with the challenge in the PAYMENT-REQUIRED header and body; the gateway signs EIP-3009 for Fuji XSGD (0xd769…c2A5) using only challenge-derived values and retries with PAYMENT-SIGNATURE.
• You need: a funded Fuji XSGD wallet (AGENT_PRIVATE_KEY in .env — organizers fund your address, send it in).

Production — passphrase, Base USDC, real cards (NETWORK_PROFILE=event-prod):

• MCP: https://card.straitsx.ai/mcp (streamable HTTP)
• Tools: get_virtual_card { passphrase, amount_usd (5–50) }, view_virtual_card { passphrase, card_opaque_id, settlement_tx }
• Custodial: no wallet, no signing — StraitsX settles USDC on Base mainnet (chain 8453) from their payer and returns { card_opaque_id, iframe_url, amount_usd, settlement_tx, payer }.
• You need: a per-team passphrase (GATEWAY_PASSPHRASE in .env) — distribution: see docs/ASKS.md.

6. The flagship example

examples/shopping-agent/ — one file, scripted mode (no LLM key), a real Anthropic tool-use chat mode, and a --handoff mode that funds a card and hands a human a checklist for any real-merchant checkout (automating a real merchant's checkout is deliberately unsupported: merchant ToS + card material is one-view secret).

7. Safety rails

• The gateway is a pure spec client. payTo, asset, amount, network, and the EIP-712 domain come only from the live 402 challenge. Gateway env holds endpoints, its key, and caps — CI greps enforce zero hardcoded addresses in packages/card-gateway/src.
• Caps and gates: MAX_CARD_AMOUNT (human units) rejects over-sized challenges; ALLOWED_NETWORKS pins CAIP-2 networks; ISSUER_ORIGIN_ALLOWLIST pins where paid POSTs may go; AUTO_PAY=false forces a two-step approve_payment flow.
• Card secrecy: card material and one-time view URLs render once; the gateway redacts card material and PAYMENT-SIGNATURE values from all logs. Never paste card details into a chat.
• Never paid-probe the live cardapi from tests/scripts. Automated checks are limited to MCP discovery, unpaid 402 probes, and local signing (an unfunded paid POST still burns StraitsX relayer gas at settlement). npm run live-check is the safe end-to-end proof — it hard-sets the dry-run stop.
• Keys: npm run setup generates a throwaway event key and prints the address only. Don't reuse personal keys.

8. Hackathon rules of engagement

• One wallet per team; submit your address for whitelisting and funding when asked.
• Cards are single-use and one-view. Lost the view? Issue a new card — there is no re-render.
• Rate limits and per-card caps (5–30 SGD sandbox, 5–50 USD prod) are enforced server-side; the gateway's own caps should be at or below them.
• Be nice to the shared live endpoints — npm run doctor before asking for help.

9. Troubleshooting

npm run doctor first — it decodes the live 402 and tells you asset/amount/network the issuer actually quoted. Then see the symptom→fix table in docs/PARTICIPANT_GUIDE.md. Error codes returned by the gateway map 1:1 to the spec §6 catalog (each carries how_to_fix).

10. Repo map

packages/protocol       wire types, codec, errors, EIP-3009, domains (single source of truth)
packages/card-gateway   participant sidecar: MCP (stdio/HTTP) + REST, pure x402 client
packages/conformance    MUST/SHOULD conformance runner (challenge-driven, live-safe by default)
apps/demo-store         stateless Luhn-only checkout + GET /catalog
examples/               shopping agent (flagship), Claude Code, curl walkthroughs
profiles/               checked-in per-scenario env wiring (see §4)
docs/                   participant guide, event-day runbook, open asks

11. Scripts

Command	What it does
npm run setup	copy .env, generate agent key (prints address only)
npm run stack	boot the demo store + gateway (issuer = live StraitsX endpoints)
npm run doctor	health table incl. live-sandbox SSE + unpaid cardapi probe + XSGD balance
npm run live-check	safe live dry run: discovery → 402 → sign, paid POST never sent
npm run test / typecheck	vitest + strict TS
npm run conformance -- --target <url>	run the conformance suite against any issuer (live-safe by default)