---
name: x402engine
description: Discover and use pay-per-call APIs within a budget.
metadata:
  hermes:
    tags: [x402, api, images, code, crypto, travel]
---

# x402engine

Use the local `x402engine-mcp@1.1.1` server to discover services and call its installed tools. Discovery and health checks are free. Paid tools use a dedicated payer wallet and USDC on Base or Solana; provider API keys and subscriptions are not required.

## When to Use

Use when the user requests x402engine, wants to inspect pay-per-call services, or needs an available external tool for their task.

## Prerequisites

Use the already-connected `x402engine-mcp@1.1.1` tools. If they are absent, give the user the [manual Hermes setup guide](https://x402engine.app/docs/hermes/) and use free HTTP discovery in the meantime. This skill does not install software, change agent settings or manage credentials.

Paid tools require a dedicated payer wallet configured by the user. Never request a private key in chat, read it into model context, or include it in a command, URL or output.

`X402_MAX_PAYMENT_USD` is a per-request ceiling, not a session budget. Loading the skill, installing the server, and configuring a wallet do not authorize spending. Use the user's existing task and spending authorization; if no paid budget is authorized, show the price and obtain authorization before calling a paid tool. Keep a running total for multi-call work and stay within both the request ceiling and the task budget.

## Choose and execute

1. Call `discover_services` to get the current catalog, availability, input schema, prices and networks. Use `service_health` if current service health will affect the choice. Prefer current discovery over prices embedded in an older tool description.
2. Match the task to an installed MCP tool. Hermes may prefix tool names with the server name; use the names and input schemas actually exposed in the current session. The full gateway catalog is broader than this package's callable tool set: discovering a chat, video or speech route does not create an MCP tool for it.
3. Check required inputs and authorized cost before making the call. Skip services whose `capabilities.available` is false. For travel, use future dates and follow the live route's parameter requirements.
4. Call once and inspect the result for an error as well as successful data. A transport-level MCP success alone does not establish API success. Return the useful output, source or media URL and the known cost; do not describe a `402` quote as a completed purchase.
5. If the result contains a queued job and `status_url`, poll that URL without another payment. Treat its token as private. For a timeout or unclear paid result, retain the receipt/job ID and check status before considering another paid call. Do not automatically replay a paid operation.

## Useful workflows

| User's task | Installed tool | Example inputs |
| --- | --- | --- |
| Browse available services and prices | `discover_services` | `{}` |
| Create an image | `generate_image` | `{"prompt":"A red sailboat on a calm lake at sunrise","tier":"fast"}` |
| Run a short calculation | `execute_code` | `{"language":"python","code":"print(sum([12, 18, 25]))"}` |
| Get crypto prices | `get_crypto_price` | `{"ids":"bitcoin,ethereum","currencies":"usd"}` |
| Transcribe a public audio file | `transcribe_audio` | Provide the user's public `audio_url` |
| Search flights | `search_flights` | Provide `origin`, `destination` and a future `departureDate` |

For a capability absent from the installed tool list, explain the integration limit and consult the gateway's [API documentation](https://x402engine.app/docs/) if the user wants a direct x402 client. Do not invent tools, treat the discovery-only public `/mcp` route as an execution server, or repurpose a wallet to make unrelated transfers.

## Free discovery fallback

Without the MCP, retrieve `https://x402engine.app/.well-known/x402.json` or `https://x402engine.app/api/services`. These return metadata without signing a payment. Current API contracts and payment networks are also described in `https://x402engine.app/openapi.json`.