three.ws Agent Payments

@three-ws/agentcore-payments-mcp

MCP server for three.ws Agent Payment Sessions — govern agent x402 spending without exposing private keys.

Concept

The agent does not hold a wallet. It proposes spend. Governance enforces policy.

A Payment Session is a budget envelope you fund once from your three.ws credits. You hand an agent the session bearer token; the agent calls paid x402 endpoints through this server. The platform's wallet signs every transaction. The session's allowlist, per-transaction ceiling, and total budget are enforced atomically on the server — the agent can never overspend.

Quick start

# Configureexport THREE_WS_SESSION="<the value of your __Host-sid cookie>"export PAYMENT_SESSION_TOKEN="pss_<session-id>_<random>"
# Runnpx @three-ws/agentcore-payments-mcp

MCP client config (~/.cursor/mcp.json, Claude Desktop, etc.):

{  "mcpServers": {    "three-ws-payments": {      "command": "npx",      "args": ["-y", "@three-ws/agentcore-payments-mcp"],      "env": {        "THREE_WS_SESSION": "<the value of your __Host-sid cookie>",        "PAYMENT_SESSION_TOKEN": "pss_..."      }    }  }}

Environment variables

Tools

create_payment_session

Create a new session funded from your credits.

{  "budget_usd": 10.00,  "label": "Research agent — June sprint",  "expiry_seconds": 86400,  "max_per_tx_usd": 0.50,  "allowed_hosts": ["api.example.com", "data.provider.io"],  "network": "solana"}

Returns { session, token }. The token is shown once — store it immediately.

pay_with_session

Pay an x402 endpoint using a session token. The platform wallet signs; your session's policy is enforced.

{  "url": "https://api.example.com/data",  "method": "GET",  "session_token": "pss_...",  "idempotency_key": "run-42-fetch-data"}

Returns { ok, paid, result, payment, session } with the tx hash, explorer link, and updated budget.

If session_token is omitted, the PAYMENT_SESSION_TOKEN env var is used.

check_payment_session

Inspect a session's budget, status, and recent payments.

{ "session_id": "...", "include_executions": true }

list_payment_sessions

List all sessions for the authenticated user, with aggregate stats.

{ "status": "active", "limit": 20 }

cancel_payment_session

Cancel a session and refund the un-spent budget to your credits.

{ "session_id": "..." }

Network support

Integrating with @three-ws/x402-mcp

The existing pay_and_call tool in @three-ws/x402-mcp now accepts session_token directly:

{  "url": "https://api.example.com/endpoint",  "session_token": "pss_...",  "confirm": true}

This routes the payment through /api/pay/execute instead of signing locally — the session's governance policy applies.

Examples

Runnable, no-payment examples live in examples/:

node examples/list-tools.mjs       # every tool with its schema and safety annotationsnode examples/plan-a-session.mjs   # read live x402 prices, print the policy to authorize

Neither one holds a wallet, reads a credential, or calls pay_with_session, so nothing is signed and nothing is spent. plan-a-session.mjs is the habit worth copying: read what an endpoint actually charges before you decide what budget to authorize. See examples/README.md.

Session lifecycle

create (budget debited from credits)  └─ active → pay_with_session calls spend against budget       ├─ exhausted (budget fully consumed)       ├─ expired (TTL elapsed — cron refunds remaining budget)       └─ cancelled (manual — remaining budget refunded immediately)

Programmatic use

The package entry point exports TOOLS (every tool definition: name, title, description, inputSchema, annotations, handler) and buildServer(), which returns a fully-registered McpServer with no transport attached. Importing is side-effect free and needs no credential, so you can mount these tools inside a host of your own or inspect the surface offline; a credential is only required when a handler actually runs.

// run with: THREE_WS_SESSION=<your __Host-sid value> node this-file.mjsimport { TOOLS, buildServer } from '@three-ws/agentcore-payments-mcp';
for (const tool of TOOLS) {	const kind = tool.annotations.readOnlyHint ? 'read ' : 'write';	console.log(`${kind} ${tool.name}`);}
// A tool handler is a plain async function against the live API.const list = TOOLS.find((t) => t.name === 'list_payment_sessions');console.log(await list.handler({ limit: 3 }));
// Or hand the whole registered server to your own MCP transport.buildServer();

Security properties

• No key exposure: the session token is a time-bounded, HMAC-signed grant. Compromising it lets an attacker spend up to the remaining budget at allowed hosts — nothing more.
• Atomic budget enforcement: concurrent payments use a SQL UPDATE … WHERE remaining >= amount RETURNING — two simultaneous requests can never collectively overspend.
• Allowlist: if allowed_hosts is set, the governor rejects any request to a host not on the list before signing.
• Per-transaction cap: max_per_tx_usd prevents a single large payment draining the entire budget.
• SSRF protection: all x402 target URLs are validated against a public-IP allowlist and DNS-resolved server-side before any payment is signed.