# Peerlytics Paid API — LLM Integration Guide

## Overview
ZKP2P protocol analytics & explorer API for deposits, intents, market data, and live events.

## Base URL
https://peerlytics.xyz/api/v1

## Authentication

### Option 1: API Key
Header: `x-api-key: pk_live_your_key_here`
Or: `Authorization: Bearer pk_live_your_key_here`

### Option 2: x402 Pay-Per-Request (USDC on Base)
No account or API key needed. Uses the x402 payment protocol (HTTP 402) by Coinbase.

Flow:
1. Send a request with no API key → receive 402 with payment requirements in body and `PAYMENT-REQUIRED` header (base64 JSON)
2. Build a payment payload using an x402 client library (e.g., `@x402/evm/exact/client`)
3. Retry the request with the payment in the `PAYMENT-SIGNATURE` header (base64-encoded JSON). Legacy `X-PAYMENT` is also accepted.
4. Receive your data + `X-Payment-TxHash` header with the settlement transaction (also available as `PAYMENT-RESPONSE` base64 JSON)

Pricing:
- Analytics endpoints: $0.001 per request
- Explorer endpoints: $0.0005 per request

x402 is supported on all endpoints except `/activity/stream` (SSE streaming).

Libraries: https://github.com/coinbase/x402

## Agent Integration Guide
https://peerlytics.xyz/agents (x402 flow, code examples, common workflows)

## OpenAPI Spec
https://peerlytics.xyz/api/openapi (add ?download=1 for file download)

## Rate Limits (per minute)
- Free tier: 60 rpm (analytics), 120 rpm (explorer)
- Paid credits: 180 rpm (analytics), 300 rpm (explorer) while paid credits remain

## Credits
- 1 request = 1 credit
- Free tier: 1,000/month (resets monthly)
- Paid credits consumed after free credits
- Credits are consumed only on 2xx responses

## Response Headers
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset
- X-Credits-Remaining (API key only)
- X-Credits-Source (paid|free, API key only)
- X-Payment-Method (api-key|x402)
- X-Payment-TxHash (x402 only, on-chain settlement tx)
- PAYMENT-REQUIRED (402 responses, x402 payment requirements base64 JSON)
- PAYMENT-RESPONSE (2xx responses, x402 settlement response base64 JSON)
- X-PAYMENT-REQUIRED (legacy, JSON string)
- X-PAYMENT-RESPONSE (legacy, base64 JSON)

## Error Format
Auth/rate/credit errors:
{"error": {"status": 401, "code": "invalid_api_key", "message": "..."}}

Some endpoint validation errors return:
{"success": false, "error": "invalid_range"}

---

# ANALYTICS ENDPOINTS

## GET /analytics/summary
Protocol summary metrics.
No parameters.

## GET /analytics/period
Full analytics payload.
Params:
- range: mtd | 3mtd | ytd | q1 | q2 | q3 | q4 | all | custom | wrapped_2025
- start: YYYY-MM-DD (required if range=custom)
- end: YYYY-MM-DD (required if range=custom)
- currency: repeatable or comma-separated currency codes (USD, EUR, GBP, ...)
- verifier: repeatable verifier addresses (0x...)
- platform: alias of verifier (repeatable)

## GET /analytics/{slice}
Slice: overview | liquidity | volume | activity | flows | performance
Params: same as /analytics/period

## GET /analytics/leaderboard
Maker/taker leaderboard. Supports pagination to retrieve beyond top 100.
Params:
- limit: 1-100 (default: 20)
- offset: number (default: 0)

## GET /analytics/attribution
Intent attribution data.
No parameters.

## GET /analytics/deposit-attribution
Deposit attribution data.
No parameters.

## GET /analytics/chunk
Large dataset chunks (for lazy loading).
Params:
- range: mtd | 3mtd | ytd | all
- chunk: daily | hourly | flows | deposits

---

# EXPLORER ENDPOINTS

## GET /explorer/search
Search intents, deposits, or addresses.
Params:
- q: string (required)
- type: tx_or_hash | address | deposit_id (optional override)
- role: owner | taker | recipient | verifier (optional, for address searches)
- limit: 1-200 (default: 100)
- offset: number (default: 0)

## GET /explorer/deposit/{id}
Deposit details by composite ID (0xescrow_123) or numeric ID.
Params:
- limit: intents per page (default: 100)
- offset: pagination offset (default: 0)

## GET /explorer/intent/{hash}
Intent details by hash or related tx hash.

## GET /explorer/address/{address}
Address activity (deposits + intents).
Params:
- limit: 1-200 (default: 100)
- offset: number (default: 0)

## GET /explorer/maker/{address}
Maker portfolio and performance.

## GET /explorer/verifier/{address}
Verifier stats and flows.
Params:
- limit: 1-100 (default: 50)
- offset: number (default: 0)

---

# DEPOSITS ENDPOINT

## GET /deposits
Query deposits with filters.
Params (at least one required):
- depositor: address (maker)
- delegate: address
- platform: platform id (repeatable) — see /meta/platforms
- currency: code or 0x hash (repeatable) — see /meta/currencies
- status: ACTIVE | CLOSED | WITHDRAWN
- accepting: true | false
- limit: 1-200 (default: 50)
- offset: number (default: 0)

---

# INTENTS ENDPOINT

## GET /intents
Query intents with filters.
Params (at least one required):
- owner: address (alias: taker)
- recipient: address (alias: toAddress)
- verifier: address
- depositId: numeric or composite (repeatable)
- status: signaled | fulfilled | completed | pruned (repeatable, comma-separated)
- limit: 1-200 (default: 50)
- offset: number (default: 0)

Notes:
- fulfilled/completed include manually released intents
- pruned matches PRUNED* statuses

---

# ORDERBOOK ENDPOINT

## GET /orderbook
Full network orderbook with rate levels, 24h activity, global stats, and FX mid-rates.
Params:
- currency: fiat currency code (USD, GBP, EUR). Without filter returns top 6 by liquidity.
- platform: payment platform name (Revolut, Monzo, Venmo)
- minSize: minimum USD liquidity per level (default: 50)

Response includes:
- stats: totalLiquidityUsd, activeMakers, volume24hUsd, activeIntents
- orderbooks: array of currencies, each with rate levels (rate, totalLiquidityUsd, depositCount, platforms, topDeposit), totalLiquidityUsd, bestRate, fxMidRate
- activity: 24h events (signal, fulfill, prune) with amountUsd, currency, platform, timestamp
- filters.available: currencies and platforms present in the orderbook

---

# MARKET ENDPOINT

## GET /market/summary
Current market rates and liquidity by platform/currency.
Params:
- platform: platform id (repeatable)
- currency: currency code (repeatable)
- includeRates: true | false (default: false)
- limit: 1-500 (default: 200)
- offset: number (default: 0)

---

# ACTIVITY ENDPOINTS

## GET /activity
Recent protocol events (intents + deposits).
Params:
- type: intent_signaled | intent_fulfilled | intent_pruned | deposit_created | deposit_topup | deposit_withdrawn | deposit_closed | deposit_rate_updated (aliases supported)
- intentHash: string (repeatable)
- depositId: string (repeatable)
- address: address (repeatable) — matches owner/toAddress/depositor/fundsTransferredTo
- owner: address
- depositor: address
- recipient: address
- since / after: unix seconds | ms | ISO timestamp
- limit: 1-200 (default: 50)
- offset: number (default: 0)

## GET /activity/stream
Server-Sent Events (SSE) for real-time events.
Params:
- type: same as /activity (aliases supported)
- since / after: unix seconds | ms | ISO timestamp
- limit: 1-200 (default: 100)
- intervalMs: 2000-30000 (default: 5000)

Events:
- activity: event payload
- cursor: lastSent timestamp
- error: error payload

---

# METADATA ENDPOINTS

## GET /meta/platforms
List of supported payment platforms with method hashes.

## GET /meta/currencies
List of supported fiat currencies with hashes.

---

# HISTORY ENDPOINTS

## GET /makers/{address}/history
Maker aggregates + recent deposits/intents.

## GET /takers/{address}/history
Taker aggregates + recent intents.

---

# EXAMPLES

## Get active Revolut GBP deposits
curl -H "x-api-key: pk_live_xxx" \
  "https://peerlytics.xyz/api/v1/deposits?platform=revolut&currency=GBP&accepting=true&limit=20"

## Get fulfilled intents for an address
curl -H "x-api-key: pk_live_xxx" \
  "https://peerlytics.xyz/api/v1/intents?owner=0x1234...&status=fulfilled&limit=50"

## Get GBP orderbook via Revolut
curl -H "x-api-key: pk_live_xxx" \
  "https://peerlytics.xyz/api/v1/orderbook?currency=GBP&platform=Revolut"

## Get market rates for EUR
curl -H "x-api-key: pk_live_xxx" \
  "https://peerlytics.xyz/api/v1/market/summary?currency=EUR"

## Pay-per-request with x402 (no API key needed)
# Step 1: Get payment requirements
curl "https://peerlytics.xyz/api/v1/orderbook"
# Returns 402 with x402 payment requirements

# Step 2: Use an x402 client to build payment and retry
# See https://github.com/coinbase/x402 for client libraries

## Stream recent fulfilled events (SSE)
const source = new EventSource("https://peerlytics.xyz/api/v1/activity/stream?type=intent_fulfilled");
source.addEventListener("activity", (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
});

---

# SUPPORT
- Email: gm@galleonlabs.io
- X: https://x.com/davyjones0x
- Telegram: https://t.me/DavyJones_0x

# AGENT SKILLS

Peer Agent Skills provide programmatic access to protocol data for AI agents.

Source: https://github.com/zkp2p/zkp2p-skills

Install: `cp -r skills/<skill> .claude/skills/<skill>`

Key skills:
- `/analyze-peer-protocol` — Protocol health, volume trends, liquidity, leaderboards
- `/look-up-peer-data` — Search deposits, intents, addresses, maker portfolios
- `/monitor-peer-activity` — Real-time protocol events (polling or SSE streaming)
- `/check-fx-rates` — Live fiat-to-USDC rates, spreads, and liquidity

Works with Claude Code, Codex, OpenClaw, Cursor, Gemini CLI, and any AgentSkills-compatible runtime.

---

# NOTES
- Timestamps can be unix seconds, unix ms, or ISO strings (where supported)
- Addresses are case-insensitive
- Lists can be comma-separated or repeated params
- Internal profile/notification endpoints are not exposed