---
name: peerlytics
description: Query the ZKP2P protocol analytics, explorer, orderbook, and trading data via the Peerlytics v1 API. Use when the user asks about protocol metrics, deposits, intents, makers, takers, integrators, platforms, vaults, or needs a typed client for ZKP2P data. Covers auth (API key or x402 pay-per-request), pagination, error handling, and outbound webhooks.
---

# Peerlytics skill

Peerlytics is the data + API layer for the ZKP2P peer-to-peer USDC ↔ fiat protocol on Base. This skill turns "I need protocol data" into a working integration.

- **Base URL:** `https://peerlytics.xyz/api/v1`
- **SDK:** `@peerlytics/sdk` (TypeScript, ESM + CJS)
- **OpenAPI:** `https://peerlytics.xyz/api/openapi` (JSON)
- **llms.txt:** `https://peerlytics.xyz/llms.txt`
- **Full reference:** `https://peerlytics.xyz/llms-full.txt`
- **Starters:** `https://github.com/ADWilkinson/usdctofiat-peerlytics-starters`
- **OpenAPI discovery:** `https://peerlytics.xyz/.well-known/openapi.json`

## When to reach for this skill

| User intent                             | Entry point                                                     |
| --------------------------------------- | --------------------------------------------------------------- |
| "What's the protocol doing this month?" | `client.getProtocolSummary()`                                   |
| "Show investor-grade view"              | `client.getProtocolOverview("mtd" \| "3mtd" \| "ytd" \| "all")` |
| "Find a deposit / address / ENS"        | `client.search("vitalik.eth")`                                  |
| "List active deposits"                  | `client.getDeposits({ platform: "revolut" })`                   |
| "Tail live events"                      | `client.getActivity({ limit: 100 })` or SSE `/activity/stream`  |
| "Live orderbook"                        | `client.getOrderbook({ currency: "GBP" })`                      |
| "Vault analytics"                       | `client.getVaultsOverview()` / `client.getVault(id)`            |
| "Integrator attribution"                | `client.getIntegrator(code)`                                    |
| "Issue or rotate API keys"              | `/api/v1/account/keys` (signed wallet request)                  |
| "Register outbound webhooks"            | `/api/v1/account/webhooks` (Pro plan / paid credits)            |

## Install and bootstrap

```bash
npm install @peerlytics/sdk
```

```ts
import { Peerlytics } from "@peerlytics/sdk";

const client = new Peerlytics({ apiKey: process.env.PEERLYTICS_API_KEY });
// or: new Peerlytics() for public endpoints
```

## Auth modes

1. **API key** — header `x-api-key: pk_live_...` or `Authorization: Bearer pk_live_...`. Free tier is 1,000 requests / month. Paid credit packs upgrade you to the Pro tier (180 rpm analytics, 300 rpm explorer).
2. **x402 pay-per-request** — no account. First request returns HTTP 402 with payment requirements; retry with `PAYMENT-SIGNATURE` base64 JSON header. $0.001 per request on Base USDC.

x402 is supported on every endpoint except `/activity/stream` (SSE needs an API key).

## Response envelope

Most `/api/v1/*` endpoints return `{ success: true, data: <payload> }`. The SDK unwraps this. Hitting the API directly, read `response.data`.

List endpoints wrap into a paginated object:

```json
{ "success": true, "data": { "events": [...], "count": 42, "hasMore": true, "limit": 50, "offset": 0 } }
```

Iterate `data.events`, `data.deposits`, `data.intents`, `data.markets` — never treat `data` as an array.

## Required filters

The API rejects empty list queries with `400 missing_filter`. The SDK throws `ValidationError` before the network call.

- `getDeposits` — at least one of `depositor`, `delegate`, `platform`, `currency`
- `getIntents` — at least one of `owner`, `recipient`, `verifier`, `depositId`, `status`

## Errors

All auth / rate / credit errors share one shape:

```json
{ "error": { "status": 429, "code": "rate_limited", "message": "..." } }
```

Common codes: `missing_api_key`, `invalid_api_key`, `rate_limited`, `insufficient_credits`, `invalid_payment`, `x402_settlement_failed`, `domain_not_allowed`, `ip_not_allowed`.

The SDK raises `PeerlyticsError`, `RateLimitError`, `NotFoundError`, `ValidationError`. All subclasses of `Error`.

## Outbound webhooks (Pro / paid credits only)

Register endpoints via `/api/v1/account/webhooks`. Events delivered:

- `deposit.created`
- `intent.created`
- `intent.filled`
- `rate.updated`

Each delivery carries `X-Peerlytics-Signature: t=<unix>,v1=<hex>` (HMAC-SHA256 over `{timestamp}.{raw body}`), `X-Peerlytics-Event`, and `X-Peerlytics-Delivery-Id`. Replay window is 5 minutes. Dispatcher retries up to 5 times with exponential backoff, then parks the delivery in the delivery log.

## Credit packs

| Pack    | USDC | Credits |
| ------- | ---- | ------- |
| Starter | $10  | 50,000  |
| Growth  | $29  | 150,000 |
| Scale   | $99  | 600,000 |

Top up via `/api/v1/account/checkout` (returns a ZKP2P Pay checkout URL).

## Full endpoint map

Analytics (5): `summary`, `overview`, `leaderboard`, `vaults`, `timeseries`
Explorer (11): `search`, `deposit/{id}`, `intent/{hash}`, `address/{address}`, `maker/{address}`, `verifier/{address}`, `taker/{address}`, `integrator/{code}`, `platform/{platform}`, `delegate/{address}`, `vault/{id}`
Data (6): `deposits`, `intents`, `orderbook`, `market/summary`, `activity`, `activity/stream`
Meta (2): `meta/platforms`, `meta/currencies`
History (2): `makers/{address}/history`, `takers/{address}/history`
Account (4 + webhooks CRUD): `account/keys`, `account/credits`, `account/checkout`, `account/webhooks`

## Rules for agents

- Always read `response.data` when talking to the raw API.
- Always pass at least one filter to list endpoints.
- Don't bypass `ValidationError` — the SDK is mirroring server validation.
- Don't reuse one API key across tenants; issue one per integration and scope via `allowedDomains` / `allowedIps`.
- If building a server-to-server integration, prefer API keys (domain restrictions won't apply without an `Origin`/`Referer`). If building an agent bot on a new wallet, prefer x402 — pay only when you run.
- Raw OpenAPI JSON is at `/api/openapi` — feed it directly to any tool-generating LLM flow.
- The canonical machine-readable docs live at `/llms-full.txt`. Pull it at session start for richer context than this skill.

## Examples

```ts
// 1. Investor view
const overview = await client.getProtocolOverview("mtd");

// 2. Paginated deposits
const page1 = await client.getDeposits({ platform: "revolut", limit: 50 });
const page2 = page1.hasMore
  ? await client.getDeposits({ platform: "revolut", limit: 50, offset: 50 })
  : null;

// 3. Orderbook snapshot
const book = await client.getOrderbook({ currency: "GBP" });

// 4. Error handling
try {
  await client.getDeposits({});
} catch (err) {
  if (err instanceof ValidationError) {
    // Known client-side guard; add a filter and retry.
  }
}
```

## Further reading

- `https://peerlytics.xyz/llms-full.txt` — full machine reference
- `https://peerlytics.xyz/api/openapi` — OpenAPI 3.1 JSON
- `https://peerlytics.xyz/pricing` — plan and credit pack details
- Source: https://github.com/ADWilkinson/galleonlabs-zkp2p/tree/main/packages/peerlytics-sdk