x402engine

intent

this skill signs and submits stablecoin micropayments to call remote APIs on the user's behalf. it routes queries against 63 available services (llms, image/video generation, flight/hotel search, crypto data, web search, code execution, audio transcription, dns resolution, ipfs pinning), matches the best service, runs a policy preflight check, and executes the call with automatic payment handling via x402 on-chain transactions. use this when you need to access a paid api and want charges deducted from a dedicated evm wallet in real time. costs range from $0.001 to $0.60 per call in usdc on base/solana or usdm on megaeth.

inputs

required

• EVM_PRIVATE_KEY (env var): secp256k1 private key that signs payment transactions. must be a dedicated wallet with limited funds, never your primary wallet. if unset, an ephemeral key is generated (no real payments possible). use one of: EVM_PRIVATE_KEY (direct) or EVM_PRIVATE_KEY_FILE (file path).

optional configuration

• EVM_PRIVATE_KEY_FILE (env var): path to a file containing the private key instead of passing it directly. use one or the other, not both.
• X402_POLICY_PATH (env var): path to a json policy file defining per-transaction spend caps, daily spending limits by chain/asset, and recipient allowlist. without this, only on-chain wallet balance enforces limits. when set, the engine is fail-closed: missing or invalid policy files deny all payments. policy file structure: {perTxCap, dailyCaps: {[chain/asset]: limit}, recipientAllowlist: [addresses]}.
• X402_STATE_PATH (env var): path to a json file tracking daily spend and rate-limit state. defaults to .x402engine-state.json. file is created if missing.
• X402_DISCOVERY_URL (env var): override service catalog url. defaults to https://x402engine.app/.well-known/x402.json. points to a json file with 63 service definitions (name, description, pricing, payTo address, chain, asset, endpoint).
• X402_AUTOPREFLIGHT (env var): set to false to skip policy checks before signing. enabled by default.
• X402_DISCOVERY_REFRESH_MS (env var): cache ttl for service catalog in milliseconds. defaults to 3600000 (1 hour).

external connections

• x402 service discovery endpoint: https://x402engine.app/.well-known/x402.json (or custom via X402_DISCOVERY_URL). publishes catalog of 63 api services with pricing, endpoints, and payment receivers.
• evm rpc endpoints (base, solana, megaeth): required by @x402/evm to broadcast signed transactions. endpoints inferred from service catalog chain declarations or configurable via viem config.
• remote api services: 63 services including openai, anthropic, fal.ai, skyvern, coingecko, serper, flightaware, booking.com, etc. each has a unique endpoint and payTo address.

runtime dependencies (npm packages)

• @x402/fetch: wraps fetch to handle 402 payment required responses and coordinate with @x402/evm.
• @x402/evm: signs permit2 transactions and broadcasts to evm rpcs.
• viem: ethereum client library for rpc calls and contract interaction.

install: cd skills/x402engine && npm install

procedure

1. Fetch and cache service catalog: call X402_DISCOVERY_URL (default: https://x402engine.app/.well-known/x402.json). cache result for X402_DISCOVERY_REFRESH_MS milliseconds. if fetch fails, retry with exponential backoff (3 retries, 2s/4s/8s). if all retries fail, return error: "service discovery unavailable; cannot route query".

2. Match query to best service: score the user's query against all 63 service descriptions using semantic matching (embedding distance or keyword overlap). rank by relevance. select top match. if score is below confidence threshold (e.g. <0.6), return "no matching service found for your query".

3. Load policy and state files: if X402_POLICY_PATH is set, parse the json file. if file is missing or invalid json, deny all payments with reason code POLICY_INVALID. load X402_STATE_PATH (create if missing). extract today's date, look up daily spend per chain/asset, and current rate-limit counters.

4. Run policy preflight checks (unless X402_AUTOPREFLIGHT is false):

   • if policy.perTxCap is set, verify call cost <= perTxCap. if exceeded, deny with reason code PER_TX_EXCEEDED.
   • if policy.dailyCaps is set, verify (today's spend on this chain/asset + call cost) <= dailyCaps[chain/asset]. if exceeded, deny with reason code DAILY_CAP_EXCEEDED.
   • if policy.recipientAllowlist is set, verify the service's payTo address is in the list. if not, deny with reason code RECIPIENT_DENIED.
   • verify wallet has sufficient balance for the call cost on the target chain. if not, deny with reason code WALLET_UNDERFUNDED.

5. Construct payment request: extract from matched service: endpoint url, payTo address, chain, asset, and expected cost. load EVM_PRIVATE_KEY or read from EVM_PRIVATE_KEY_FILE. prepare permit2 approval data (if needed) and payment intent.

6. Sign and submit transaction: use @x402/evm to sign a permit2 transaction authorizing the payment. broadcast to the appropriate evm rpc (base, solana, or megaeth). wait for on-chain confirmation (polling with 5 second intervals, timeout after 60 seconds). if broadcast fails due to insufficient gas, return "transaction failed: insufficient gas funds on [chain]". if confirmation times out, return "transaction pending; check wallet history".

7. Call remote api: use @x402/fetch with the signed transaction intent. send http request (get/post) to the service endpoint with user query params. @x402/fetch will handle 402 payment required responses by resubmitting with the signed intent. capture response. on http error (4xx/5xx), return the error message plainly. on network timeout (>30s), retry up to 2 times with exponential backoff before failing.

8. Update state file: increment X402_STATE_PATH daily spend counter for the chain/asset by the call cost. increment rate-limit counter if applicable. persist the updated state.

9. Format and return result: parse the api response. return structured data (json object with result, cost, chain, asset, timestamp, service name). do not strip the cost from the output.

decision points

• if EVM_PRIVATE_KEY and EVM_PRIVATE_KEY_FILE are both set: deny all payments with reason code ACTION_DENIED and message "only one of EVM_PRIVATE_KEY or EVM_PRIVATE_KEY_FILE may be set".

• if neither EVM_PRIVATE_KEY nor EVM_PRIVATE_KEY_FILE is set: generate an ephemeral secp256k1 key. allow read-only catalog queries and budget checks, but deny all payments with message "no private key configured; payments disabled".

• if X402_POLICY_PATH is set but file is missing or invalid json: deny all payments with reason code POLICY_INVALID and message "policy file missing or malformed; payments denied".

• if X402_POLICY_PATH is not set: enforce only on-chain balance limits. all policy preflight checks pass. spend tracking in state file is optional.

• if X402_AUTOPREFLIGHT is explicitly false: skip all policy checks (reason codes, cap validation, allowlist checks). proceed directly to signing if wallet balance is sufficient.

• if policy preflight check fails: return denial reason code and human-readable message (e.g. "daily spending limit exceeded for usdc on base: $5.00/day, already spent $4.99"). do not attempt to sign or broadcast transaction.

• if service discovery returns stale or corrupted catalog (malformed json, duplicate service ids, missing required fields): log the error, continue using the last valid cached version if available. if no cache exists, return "service catalog unavailable".

• if the matched service has cost > 0 but user's query does not require payment (e.g. user asks "what services are available"): route to a free internal service list instead of calling the paid service.

• if broadcast transaction fails due to nonce collision or mempool rejection: retry up to 1 time with a fresh nonce. if retry fails, return "transaction rejected by network; insufficient network capacity or nonce conflict".

• if api response is successful but missing expected fields: return the raw response with a warning: "[service name] returned incomplete data".

• if user asks "how much budget is left" or similar budget query: load policy and state. return a structured budget report: per-chain daily cap remaining, wallet balance, rate-limit status, timestamp. do not call any paid service.

• if api call cost is not declared in the service catalog: use a conservative estimate ($0.01) and mark the result with a cost uncertainty flag: cost_estimated: true.

output contract

all results are returned as a json object with the following structure:

{
  "success": boolean,
  "service": "service name (e.g.,