x402engine

# x402engine

Call 63 paid APIs via x402 micropayments. Each API call costs between $0.001 and $0.60, paid with USDC on Base/Solana or USDm on MegaETH.

## What this skill does

This skill signs and submits stablecoin micropayments to call remote APIs on the user's behalf. It uses the EVM_PRIVATE_KEY environment variable to sign on-chain payment transactions. Each call deducts a small amount from the wallet.

**Cost transparency:** When presenting results, include the cost of the call (e.g. "Bitcoin is $97,500 (cost: $0.001)"). If the user asks about spending, show full budget breakdown.

## Triggers
- "what's the price of bitcoin"
- "ethereum price"
- "show me trending crypto"
- "generate an image of a sunset"
- "run this python code"
- "transcribe this audio"
- "wallet activity of vitalik.eth"
- "ask gpt to explain x402"
- "scrape this url"
- "pin this to ipfs"
- "resolve vitalik.eth"
- "flights from JFK to LAX"
- "search hotels in Paris"
- "find cheap flights to Tokyo"
- "how much budget is left"
- "list available services"

## How it works
1. Fetch cached service catalog from discovery endpoint (default: https://x402engine.app/.well-known/x402.json).
2. Score query against 63 service descriptions to find best match.
3. Run policy preflight — check per-tx caps, daily caps, and recipient allowlist before signing.
4. Call service via @x402/fetch — handles 402 payment flow automatically.
5. Return structured data to the agent for natural-language presentation.

## Rules
- Present results naturally. Include the cost of each call so the user knows what was spent.
- If a payment fails due to insufficient funds, tell the user: "I need funds to access this service. Add USDC to your wallet to continue."
- If no matching service is found, say so plainly — don't expose internal routing details.
- Policy limits are authoritative — do not bypass spend caps or recipient allowlists.
- Keep all decisions explainable with reason codes internally.

## Security

### Required credential
- **EVM_PRIVATE_KEY** (required) — signs payment transactions. Use a dedicated wallet with limited funds — never your primary wallet. If not set, an ephemeral key is generated (no real funds, no payments possible).

### Optional configuration
These environment variables are NOT required. They provide additional controls:
- **EVM_PRIVATE_KEY_FILE** — alternative to EVM_PRIVATE_KEY; reads the key from a file instead of an env var. Use one or the other, not both.
- **X402_POLICY_PATH** — path to a JSON policy file. Defines per-transaction caps, daily spending limits, and a recipient allowlist. Without this, no spending limits are enforced beyond the wallet's on-chain balance. When configured, the engine is fail-closed: if the file is missing or invalid, all payments are denied.
- **X402_STATE_PATH** — path to a JSON file tracking daily spend and rate-limit state. Defaults to `.x402engine-state.json`.
- **X402_DISCOVERY_URL** — override the service catalog URL (default: `https://x402engine.app/.well-known/x402.json`). Use a self-hosted catalog if you don't trust the default.
- **X402_AUTOPREFLIGHT** — set to `false` to skip policy preflight checks. Enabled by default.
- **X402_DISCOVERY_REFRESH_MS** — cache TTL for the service catalog in milliseconds.

### How payments work
All payments go to the `payTo` address declared in the service catalog. The catalog is fetched from the discovery URL above. If you want to restrict which addresses can receive payments, configure a policy file with a recipient allowlist.

## Budget check
When the user asks "how much budget is left" or similar:
- Load policy and state files.
- Show daily cap remaining per chain/asset if caps are enabled.
- Show rate limit status.
- Show wallet balance.

## Dependencies
This skill requires Node.js and the following npm packages (declared in package.json):
- `@x402/fetch` — x402 payment-aware fetch wrapper
- `@x402/evm` — EVM payment scheme (Permit2 signatures)
- `viem` — Ethereum client library

Install with: `cd skills/x402engine && npm install`

## Reason Codes
- `POLICY_MISSING`, `POLICY_INVALID`
- `CHAIN_DENIED`, `ASSET_DENIED`, `RECIPIENT_DENIED`
- `PER_TX_EXCEEDED`, `DAILY_CAP_EXCEEDED`, `RATE_LIMITED`
- `ACTION_DENIED`
- `SERVICE_NOT_FOUND`
- `WALLET_UNDERFUNDED`