# Turnstiles — Machine Discovery & Endpoint Guide (`agents.md`)

> **Preview status:** This service is a preview. Responses are generated from simulated sample data. Payments are verified and settled for real, in testnet USDC on Base Sepolia testnet (`eip155:84532`), so no real money moves. Do not use the numbers for trading decisions.

Autonomous AI agents can call our endpoints directly over **x402 v2** (HTTP `402 Payment Required`) settling in **USDC on Base Sepolia testnet (`eip155:84532`)** with zero accounts, sessions, or API keys.

## Why Agents Use Turnstiles
1. **Quantitative Token Telemetry (`$0.01 USDC`):** `POST /api/v1/quests/alpha-scan/resource` returns raw numeric measurements: sell simulation boolean, buy/sell tax bps, LP lock %, block-0/1 cluster %, top-10 holder %, and 24h net flow USD. No verdicts, grades, or buy/sell signals—purchasing agents make all judgment calls.
2. **Pre-Trade Swap & MEV Telemetry (`$0.02 USDC`):** `POST /api/v1/quests/mev-shield/resource` simulates your swap pre-trade, returns price impact bps, estimated mempool leakage bps & USD, multi-DEX split route allocations (Aerodrome + Uniswap v3 / Raydium + Meteora), and relays signed transactions privately.

---

## Endpoints & Pricing

| Quest Slug | Method & Path | Price (USDC) | Atomic Units | Description |
| :--- | :--- | :--- | :--- | :--- |
| `alpha-scan` | `POST /api/v1/quests/alpha-scan/resource` | `$0.01` | `10000` | Raw token telemetry: tax bps, LP lock %, cluster %, and 24h flow numbers |
| `mev-shield` | `POST /api/v1/quests/mev-shield/resource` | `$0.02` | `20000` | Pre-trade swap simulation, leakage bps/USD, split routes & private relay |
| `wallet-pnl` | `POST /api/v1/quests/wallet-pnl/resource` | `$0.01` | `10000` | Historical wallet win rate %, trade count, realized/unrealized PnL & ROI % |
| `gas-oracle` | `POST /api/v1/quests/gas-oracle/resource` | `$0.005` | `5000` | L2 base fee, priority fee, 5m delta %, volatility % & blob utilization |
| `contract-audit` | `POST /api/v1/quests/contract-audit/resource` | `$0.02` | `20000` | Bytecode size, function selector inspection & capability boolean flags |
| `operations` | `GET /api/v1/operations/:operationId` | **FREE** | `0` | Poll pending `HTTP 202` operations without re-paying |
| `leaderboard` | `GET /api/v1/leaderboard` | **FREE** | `0` | EV-weighted agent leaderboard |

- **Settlement Asset:** USDC on Base Sepolia testnet (`0x036CbD53842c5426634e7929541eC2318f3dCF7e`)
- **Settlement Network:** Base Sepolia testnet (`eip155:84532`)
- **Pay-To Address:** `0x906817c875FdefD35f6b367dF3073c2c83Be3F20`
- **Supported Target Chains:** `base`, `solana`, `ethereum`, `arbitrum`

---

## Execution Flow
1. **Pre-Flight / Unpaid Call:** Send `POST` request with JSON body. Invalid schemas return `HTTP 400` before charging. Valid schemas without payment return `HTTP 402 Payment Required` with `availability="ready"` and `supported_token_chains`.
2. **Sign & Retry:** Decode the base64 `PAYMENT-REQUIRED` response header (the JSON body carries a readable copy), sign an EIP-3009 `exact` payment for the listed amount, and resend the same request with header `PAYMENT-SIGNATURE`. This is standard x402 v2, so any v2 client (for example `@x402/fetch`) works. The legacy v1 `X-PAYMENT` header is not accepted.
3. **Settlement:** The facilitator verifies the payment, the endpoint runs, and the payment settles only if the endpoint succeeded. The `PAYMENT-RESPONSE` header and `receipt.tx_hash` carry the settlement transaction. A failed request is never charged.
4. **Idempotent Recovery (`HTTP 202`):** If an upstream simulation takes >1,800ms, the server returns `HTTP 202 Accepted` with `operation_id` and `status_url`. Poll `GET status_url` for free—never create a duplicate payment for the same operation.
5. **Safe Retries:** Resending the same `PAYMENT-SIGNATURE` with the same body returns the stored result without charging again. Reusing it for a different body returns `HTTP 409`.

## Quick cURL Examples

```bash
# 1. Trigger 402 Challenge on Alpha-Scan ($0.01 USDC)
curl -i -X POST 'http://localhost:3000/api/v1/quests/alpha-scan/resource' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"base","tokenAddress":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

# 2. Trigger 402 Challenge on MEV-Shield ($0.02 USDC)
curl -i -X POST 'http://localhost:3000/api/v1/quests/mev-shield/resource' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"base","mode":"simulate_only","swap":{"tokenIn":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","tokenOut":"0x4200000000000000000000000000000000000006","amountInAtomic":"25000000000","senderAddress":"0x1111111111111111111111111111111111111111"}}'
```

---

## Legal, Non-Reliance & Attribution Rules

1. **Non-Fiduciary Status:** All telemetry, simulation outputs, gas measurements, bytecode selectors, and wallet metrics are provided **strictly as raw quantitative numbers for technical research and informational purposes**. They do **NOT** constitute financial, investment, accounting, tax, or legal trading advice, and contain no buy/sell signals, grades, or recommendations.
2. **Probabilistic Measurements:** On-chain simulations and bytecode inspections are provided **"AS IS"** and **"AS AVAILABLE"** without warranties of merchantability or fitness for any purpose.
3. **Mandatory Downstream Flowdown:** Any autonomous agent, UI developer, or downstream client that displays or relays data returned by these endpoints **MUST retain and prominently present the inline `disclaimer` field** to end-users. You may not represent these outputs as trade signals or fiduciary recommendations.
4. **Limitation of Liability:** To the maximum extent permitted by applicable law, in no event shall the protocol operators be liable for trading losses, slippage, exploits, or bad bets resulting from the consumption of these APIs.