ZKP2P API Guide: Protocol Data for Developers and Agents

The ZKP2P protocol runs a peer-to-peer USDC/fiat exchange on Base with a deep Envio-indexed on-chain state, but calling the raw GraphQL indexer directly is the wrong abstraction for most use cases. You want pre-aggregated orderbook rows, normalized platform names, cached market intelligence, and structured analytics — which is exactly what the Peerlytics API provides. This guide walks through the 24 endpoints, the two auth modes, and what to use when.

Base URL and authentication

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

Every paid endpoint supports two authentication modes. You pick whichever fits your environment.

• API key. Provision a key via the developers page, pre-fund your account with credits, and send the key in an X-API-Key header. Best for server-to-server integrations where you can rotate keys on a schedule.
• x402 pay-per-request. No account needed. Each request includes an x402 payment proof in Base USDC covering the per-request cost. Ideal for AI agents, one-off scripts, and ephemeral workloads. See the x402 payment API guide for details.

Response envelope

Every endpoint returns a consistent response shape: an object with { success: true, data: <payload> }. List endpoints (/deposits, /intents, /activity, /market/summary) return a paginated object inside data, not a raw array. The @peerlytics/sdk package unwraps envelopes and validates required filters client-side.

Endpoint map

Analytics (4 endpoints)

• GET /analytics/summary — investor summary buckets for a period (mtd, 3mtd, ytd, all)
• GET /analytics/overview — full investor payload with volume, liquidity, maker/taker splits, and platform breakdowns
• GET /analytics/leaderboard — maker and taker leaderboards by volume
• GET /analytics/vaults — aggregated vault and rate-manager statistics

Explorer (7 endpoints)

• GET /explorer/search?q=<query> — universal search across addresses, intents, deposits, and tx hashes
• GET /explorer/deposit/{id} — deposit details by numeric ID
• GET /explorer/intent/{hash} — intent details by hash
• GET /explorer/address/{address} — combined maker + taker activity
• GET /explorer/maker/{address} — maker-specific portfolio and stats
• GET /explorer/verifier/{address} — verifier statistics
• GET /explorer/vault/{id} — delegation vault / rate-manager detail

Data feeds (6 endpoints)

• GET /deposits — paginated deposit list, requires one of depositor, delegate, platform, currency
• GET /intents — paginated intent list with status filters
• GET /orderbook — canonical orderbook projection with full depth
• GET /market/summary — cross-market rate comparison, percentile rankings, time-to-fill signals
• GET /activity — recent signaling and fulfillment events
• GET /activity/stream — Server-Sent Event stream of live protocol activity

Meta + history (4 endpoints)

• GET /meta/platforms — supported payment platforms catalog
• GET /meta/currencies — supported currencies catalog
• GET /makers/{address}/history — maker deposit and fill history
• GET /takers/{address}/history — taker intent and purchase history

Account management (3 endpoints)

Only relevant for API-key mode:

• GET /account/keys — list keys for the authenticated account
• GET /account/credits — current credit balance
• POST /account/checkout — create a top-up checkout session

OpenAPI schema

Peerlytics publishes a full OpenAPI 3.1 spec at peerlytics.xyz/.well-known/openapi.json. Generate typed clients for any language via openapi-python-client, oapi-codegen, progenitor, etc. AI agents that crawl .well-known/ directories will auto-discover the API surface.

Integration patterns

Market-making bots

For a market-making bot tracking competitor rates: poll /orderbook every 30 seconds with platform and currency filters, compare to your rates, and issue rate updates via the ZKP2P smart contracts directly. Peerlytics handles the read side.

Analytics dashboards

Call /analytics/overview with a period parameter rather than computing aggregates client-side. Peerlytics' analytics cron pre-computes these payloads every 30 minutes.

Explorer frontends

For search UIs: call /explorer/search with the user's query first — it disambiguates addresses, intent hashes, deposit IDs, tx hashes, and ENS names, and returns a typed response pointing to the right detail endpoint.

AI agents and autonomous workflows

Use x402 auth to avoid manual API key provisioning. The @peerlytics/sdk package handles the x402 envelope automatically — pass a funded wallet, the SDK signs each request and includes the payment proof. Full walkthrough in the x402 guide.

Rate limits and SLAs

Per-key rate limits default to 100 req/s. x402 requests have a higher burst limit but share the same overall ceiling. Analytics endpoints are cached with 30-60 second TTLs; orderbook and intents are near-realtime backed by Envio's ~2 second indexing delay. Use /activity/stream instead of polling when you need tick-level accuracy.

Where to go next

• Developer docs — API keys, pricing, credit top-up
• x402 payment API guide — for AI agents
• What is P2P crypto trading?
• Peer orderbook — public read-only view of the same data

Frequently asked questions

What is the ZKP2P API?

A REST interface to the ZKP2P peer-to-peer USDC/fiat protocol on Base. Peerlytics publishes a productized version with 24 endpoints for analytics, explorer lookups, orderbook data, market summaries, and per-address history. Auth via API key or x402 pay-per-request.

Is the Peerlytics API free?

Paid endpoints charge $0.001 per request. Static data on network.peerlytics.xyz is free.

What's the difference between Peerlytics and ZKP2P's indexer?

The indexer exposes raw protocol state via GraphQL. Peerlytics is a higher-level API that adds aggregation, caching, normalization, pricing, and pre-computed analytics. Use the indexer directly only when you need custom GraphQL queries on raw state.

Does it support Python, Go, or Rust SDKs?

The official SDK is TypeScript. Generate typed clients for any language from the OpenAPI schema at /.well-known/openapi.json.

Can AI agents use it?

Yes — x402 auth is the primary target. Agents fund requests from a USDC balance with no account signup.