# x402-tools API

This server exposes paid API endpoints protected by the [x402 protocol](https://x402.org). All endpoints respond with `402 Payment Required` until a valid x402 payment is attached. Most endpoints charge **$0.01 USDC** per request on Base mainnet (or Base Sepolia for testnet variants). The `upto` endpoint uses per-output-token billing with `Settlement-Overrides`.

Use an x402-compatible HTTP client (e.g. `fetch` from `x402-fetch`, the `x402-axios` interceptor, or AgentCash) to pay automatically.

Discovery: `GET /.well-known/x402` returns the full resource list, ownership proofs, and these instructions in machine-readable JSON.

---

## Endpoints

### GET /api/horoscope
Daily horoscope for a zodiac sign, scraped from horoscope.com and Redis-cached.

- **Cost:** $0.01 USDC on Base mainnet
- **Parameters:**
  - `sign` *(required)* — zodiac sign: `aries`, `taurus`, `gemini`, `cancer`, `leo`, `virgo`, `libra`, `scorpio`, `sagittarius`, `capricorn`, `aquarius`, `pisces`
  - `date` *(optional)* — `today` (default) or `YYYY-MM-DD` for archived horoscopes
- **Response:** `{ success: true, data: { date: string, horoscope: string } }`

---

### GET /api/horoscope/testnet
Same as `/api/horoscope` but priced on **Base Sepolia** (testnet). Supports Permit2 asset transfer and EIP-2612 / ERC-20 approval gas sponsorship extensions.

- **Cost:** $0.01 USDC on Base Sepolia
- **Parameters:** same as `/api/horoscope`
- **Response:** same as `/api/horoscope`

---

### GET /api/horoscope/testnet-permit2
Same horoscope endpoint on **Base Sepolia** using Permit2 asset transfer only (no gas-sponsoring extensions).

- **Cost:** $0.01 USDC on Base Sepolia
- **Parameters:** same as `/api/horoscope`
- **Response:** same as `/api/horoscope`

---

### GET /api/concerts
Search upcoming music concerts via the Ticketmaster Discovery API. Results are cached in Redis for 6 hours.

- **Cost:** $0.01 USDC on Base mainnet
- **Parameters:**
  - `city` *(optional)* — city name (e.g. `New York`)
  - `startDateTime` *(optional)* — ISO 8601 start of search window (e.g. `2026-05-01T00:00:00Z`)
  - `endDateTime` *(optional)* — ISO 8601 end of search window
  - `genre` *(optional)* — music genre/subgenre name (e.g. `rock`, `hip-hop`)
  - `countryCode` *(optional)* — ISO country code, default `US`
  - `page` *(optional)* — page number, default `0` (25 results per page)
  - `artists` *(optional)* — comma-separated artist names; filters results client-side by attraction name substring match
- **Response:** JSON array of concert objects from Ticketmaster

---

### GET /api/polymarket/trending
Top trending active prediction markets on Polymarket, sorted by 24-hour volume.

- **Cost:** $0.01 USDC on Base mainnet
- **Parameters:**
  - `limit` *(optional)* — max markets to return, default `5`
  - `offset` *(optional)* — pagination offset, default `0`
  - `tag_slug` *(optional)* — category filter (e.g. `sports`, `politics`, `crypto`)
- **Response:** JSON array of `{ question, liquidity, description, outcomes, outcomePrices, volume }`

---

### GET /api/polymarket/historical
Resolved (closed) Polymarket prediction markets, sorted by end date descending.

- **Cost:** $0.01 USDC on Base mainnet
- **Parameters:**
  - `limit` *(optional)* — max markets to return, default `5`
  - `offset` *(optional)* — pagination offset, default `0`
  - `tag_slug` *(optional)* — category filter
  - `slug` *(optional)* — specific market slug
  - `endDateMin` *(optional)* — filter markets resolved after this date (ISO 8601)
  - `endDateMax` *(optional)* — filter markets resolved before this date (ISO 8601)
- **Response:** JSON array of `{ question, liquidity, description, outcomes, outcomePrices, volume }`

---

### GET /api/upto/complete/testnet
Mock LLM text completion on **Base Sepolia** using the x402 `upto` (upTo) scheme. The payment authorization covers up to the maximum token count; actual settlement is reduced to the real output token count via `Settlement-Overrides`.

- **Cost:** up to $0.02 USDC on Base Sepolia ($0.0001 per output token, max 200 tokens)
- **Scheme:** `upto` — client authorizes the maximum; server settles only what was used
- **Parameters:**
  - `prompt` *(required)* — input text, max 2048 characters
  - `maxTokens` *(optional)* — integer 1–200, default `200`
- **Response:** `{ completion: string, usage: { promptChars, outputTokens, maxOutputTokens, pricePerOutputTokenAtomic, maxAuthorizedAtomic, actualChargedAtomic } }`

---

## Payment

All endpoints implement the [x402 protocol](https://x402.org):

1. Send a normal GET request to any endpoint.
2. The server returns `402 Payment Required` with a `X-Payment-Requirements` header describing the accepted payment (scheme, price, network, payTo address).
3. Attach a signed payment token in the `X-Payment` header and re-send the request.
4. The server verifies payment on-chain and returns the resource.

Recommended clients: [`x402-fetch`](https://www.npmjs.com/package/x402-fetch), [`x402-axios`](https://www.npmjs.com/package/x402-axios), or [AgentCash](https://agentcash.dev).