# web4-service

> x402-powered paid AI agent services with multi-chain EVM payment support. Pay-per-call via standard HTTP 402 micropayments — no API keys needed.

This service provides AI agent tools accessible via HTTP, with payments handled through the x402 protocol. Agents can discover services, check pricing, and pay per request using USDC on supported EVM networks.

## API Endpoints

- [Service Catalog](https://web4svc.com/agent/services): `GET /agent/services` — List all available agent services with pricing and schemas
- [Agent Discovery](https://web4svc.com/.well-known/agent-services): `GET /.well-known/agent-services` — Standard agent service manifest with absolute endpoint URLs
- [Invoke Service](https://web4svc.com/agent/services/echo/invoke): `POST /agent/services/:serviceId/invoke` — Invoke an agent service by ID (paid services require x402 payment headers)
- [Health Check](https://web4svc.com/health): `GET /health` — Service health status and uptime

## Invoke Response Format

All service invocations return a wrapper object:

```json
{
  "serviceId": "echo",
  "output": {
    // service-specific output fields
  }
}
```

Error responses use the format `{ "error": "error_code", "serviceId": "..." }` with appropriate HTTP status codes (400, 402, 404, 502, 503).

## Available Services

### Perplexity Web Search (Paid)

AI-powered web search via Perplexity. Returns answers with source citations.

- Endpoint: `POST /agent/services/perplexity-search/invoke`
- Price: configurable per deployment (default $0.03, USDC, via x402)
- Input: `{ "query": "your search query", "model": "optional model override" }`
- Output (inside `output` field): `{ "answer": "...", "citations": ["url1", "url2"], "model": "sonar-pro" }`
- `query` is required; `model` is optional

### Token Price Lookup (Paid)

Real-time token price lookup via CoinGecko. Accepts token names, symbols, or CoinGecko IDs.

- Endpoint: `POST /agent/services/token-price/invoke`
- Price: configurable per deployment (USDC, via x402)
- Input: `{ "token": "bitcoin", "currency": "usd" }`
- `token` is required (name, symbol like "BTC", or CoinGecko ID like "bitcoin"); `currency` is optional (default: "usd")
- Output (inside `output` field): `{ "id": "bitcoin", "symbol": "BTC", "name": "Bitcoin", "price": 97500.42, "currency": "usd", "change24h": 2.35, "marketCap": 1920000000000, "volume24h": 45000000000, "lastUpdated": "2025-01-01T00:00:00.000Z" }`
- `change24h`, `marketCap`, and `volume24h` may be `null` if unavailable

### ENS Resolution (Paid)

Resolve ENS names to Ethereum addresses (and vice versa) with avatar and text records.

- Endpoint: `POST /agent/services/ens-resolve/invoke`
- Price: configurable per deployment (default $0.0005, USDC, via x402)
- Input: `{ "name": "vitalik.eth" }` for forward resolution, or `{ "address": "0xd8dA..." }` for reverse resolution
- At least one of `name` or `address` is required; when both are provided, `name` takes priority
- Output (inside `output` field): `{ "name": "vitalik.eth", "address": "0xd8dA...", "avatar": "https://...", "records": { "description": "...", "url": "...", "com.twitter": "...", "com.github": "...", "org.telegram": null, "email": null } }`
- Fields that cannot be resolved return `null`

### Echo (Free)

Free utility endpoint for connectivity and payload checks. No payment required.

- Endpoint: `POST /agent/services/echo/invoke`
- Input: `{ "message": "optional text" }` — defaults to `"hello agent"` if omitted
- Output (inside `output` field): `{ "message": "hello agent", "echoedAt": "2025-01-01T00:00:00.000Z" }`

## x402 Payment Flow

1. Call a paid endpoint without payment headers.
2. Server responds with HTTP 402 and payment requirements in the `payment-required` header.
3. Client wallet creates a USDC payment on a supported EVM network.
4. Client retries with the x402 payment header and receives the service result.

Free services (like echo) skip the payment flow entirely.

## Supported Payment Networks

Payments are accepted in USDC via the PayAI facilitator. The specific networks available depend on the deployment configuration (set via `X402_PAYMENT_OPTIONS`). Query `GET /agent/services` to see the current `paymentOptions` for each paid service, which lists accepted networks.

## MCP Server

An MCP (Model Context Protocol) server is available at `mcp-server/` in the repository, enabling AI agents like Claude and Cursor to natively discover and invoke all web4-service endpoints with automatic x402 payment handling. See the [MCP server README](https://github.com/mapleeit/web4-service/tree/main/mcp-server) for setup.

## Links

- [GitHub](https://github.com/mapleeit/web4-service)
- [Facilitator](https://facilitator.payai.network)