agent integration guide
everything an ai agent needs to query zkp2p protocol data via the peerlytics api
tl;dr for agents
Peerlytics exposes 24 REST endpoints under https://peerlytics.xyz/api/v1/* covering ZKP2P P2P protocol analytics, deposits, intents, orderbook, market data, and activity.
Two auth methods: API key (header-based, requires account) or x402 pay-per-request (USDC on Base, no account needed). x402 is the recommended method for autonomous agents.
Machine-readable resources: llms.txt (full endpoint reference), OpenAPI spec (for SDK generation).
what is zkp2p
ZKP2P is a peer-to-peer protocol on Base for trading USDC against fiat currencies (USD, GBP, EUR, and more) via payment platforms like Revolut, Venmo, and Monzo. It uses zero-knowledge proofs to verify fiat payments on-chain.
Key concepts:
Deposits (Makers)
USDC liquidity posted by sellers at a specific rate and payment platform. Each deposit has a unique ID.
Intents (Takers)
Buy orders signaled against deposits. Status: signaled → fulfilled → completed (or pruned if expired).
Verifiers
Smart contracts that verify ZK proofs for specific payment platforms (Revolut, Venmo, etc).
Rates
Conversion rates are USDC per unit of fiat. A rate of 1.02 for GBP means 1 GBP = 1.02 USDC.
authentication
recommended: x402 pay-per-request
No account, no API key, no setup. Pay per request with USDC on Base using the x402 protocol by Coinbase. Ideal for autonomous agents that need immediate access.
pricing
analytics endpoints: $0.001 / request
explorer endpoints: $0.0005 / request
settlement
USDC on Base (chain ID 8453)
settlement via Coinbase CDP x402 facilitator
alternative: api key
If you have a pre-provisioned API key, pass it in the x-api-key header or Authorization: Bearer. API keys include 1,000 free credits/month. Get keys at peerlytics.xyz/developers.
x-api-key: pk_live_your_key_here
x402 pay-per-request flow
Send request without auth
API returns HTTP 402 with payment requirements in both the response body and the PAYMENT-REQUIRED header (base64 JSON). Legacy X-PAYMENT-REQUIRED is also provided.
Build payment payload
Use an x402 client library to create a signed payment from the requirements. The payment authorizes the exact amount for this request.
Retry with payment header
Resend the same request with the PAYMENT-SIGNATURE header (base64-encoded JSON). Legacy X-PAYMENT is also accepted. Receive your data + X-Payment-TxHash header (and PAYMENT-RESPONSE base64 JSON) with the settlement transaction.
import { x402Client } from "@x402/core/client";
import { x402HTTPClient } from "@x402/core/http";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const signer = toClientEvmSigner(account);
const client = new x402Client();
registerExactEvmScheme(client, { signer });
const httpClient = new x402HTTPClient(client);
async function queryWithX402(path: string) {
const url = "https://peerlytics.xyz/api/v1" + path;
// Step 1: Get payment requirements (402)
let res = await fetch(url);
if (res.status !== 402) return res.json(); // already authed (api key or previously paid)
const body = await res.json().catch(() => undefined);
const paymentRequired = httpClient.getPaymentRequiredResponse(
(name) => res.headers.get(name),
body,
);
// Step 2: Build payment payload
const payment = await httpClient.createPaymentPayload(paymentRequired);
// Step 3: Retry with payment header
res = await fetch(url, { headers: httpClient.encodePaymentSignatureHeader(payment) });
// Settlement response is also available in X-Payment-TxHash for convenience.
const settlement = httpClient.getPaymentSettleResponse((name) => res.headers.get(name));
console.log("Settlement tx:", settlement.transaction);
return res.json();
}
// Usage
const orderbook = await queryWithX402("/orderbook?currency=GBP");
const summary = await queryWithX402("/analytics/summary");import requests
import json
import base64
BASE = "https://peerlytics.xyz/api/v1"
def query_with_api_key(path: str, api_key: str) -> dict:
"""Simple API key auth (if you have one)."""
res = requests.get(f"{BASE}{path}", headers={"x-api-key": api_key})
res.raise_for_status()
return res.json()
def query_with_x402(path: str, payment_builder) -> dict:
"""x402 pay-per-request flow."""
url = f"{BASE}{path}"
# Step 1: Get payment requirements
res = requests.get(url)
if res.status_code != 402:
return res.json()
requirements = res.json()
# Step 2: Build payment (implementation depends on your x402 library)
payment = payment_builder(requirements)
# Step 3: Retry with payment
encoded = base64.b64encode(json.dumps(payment).encode()).decode()
res = requests.get(url, headers={"PAYMENT-SIGNATURE": encoded})
res.raise_for_status()
print(f"Settlement tx: {res.headers.get('X-Payment-TxHash')}")
return res.json()
# See https://github.com/coinbase/x402 for Python client librariesx402 client libraries
TypeScript: @x402/evm + @x402/core (npm) — use registerExactEvmScheme + x402HTTPClient
Full docs and more languages: github.com/coinbase/x402
common agent workflows
Use /orderbook for a complete view of live P2P liquidity grouped by currency and rate level, or /market/summary for aggregated rates per platform/currency pair.
GET https://peerlytics.xyz/api/v1/orderbook # Filter to a specific currency or platform: GET https://peerlytics.xyz/api/v1/orderbook?currency=GBP GET https://peerlytics.xyz/api/v1/orderbook?currency=EUR&platform=Revolut
Response shape: { stats, orderbooks[], activity[], filters }
Each orderbook entry has rate levels with rate, totalLiquidityUsd, depositCount, and platforms.
The fxMidRate field gives the mid-market FX rate for comparison against P2P rates.
endpoint quick reference
All endpoints are under https://peerlytics.xyz/api/v1. Full parameter details in llms.txt or the OpenAPI spec.
/orderbookFull orderbook with rate levels, stats, 24h activity, FX mid-rates
params: currency, platform, minSize
/market/summaryRates and liquidity by platform/currency
params: platform, currency, includeRates, limit
/analytics/summaryTop-level protocol summary
/analytics/periodFull analytics for a time range
params: range, start, end, currency, verifier
/analytics/{slice}Specific slice (overview, liquidity, volume, activity, flows, performance)
params: same as period
/analytics/leaderboardTop makers and takers (paginated)
params: limit, offset
/analytics/attributionIntent attribution breakdown
/explorer/searchSearch by hash, address, or deposit ID
params: q (required), type, role, limit, offset
/explorer/deposit/{id}Deposit details + linked intents
params: limit, offset
/explorer/intent/{hash}Intent details + fulfillment info
/explorer/address/{address}Address deposits + intents
params: limit, offset
/explorer/maker/{address}Maker portfolio and performance
/depositsQuery deposits (at least one filter required)
params: depositor, delegate, platform, currency, status, accepting, limit
/intentsQuery intents (at least one filter required)
params: owner, recipient, verifier, depositId, status, limit
/activityRecent events (deposits + intents)
params: type, intentHash, depositId, address, since, limit
/activity/streamSSE for real-time events (API key only)
params: type, since, limit, intervalMs
/meta/platformsSupported payment platforms + method hashes
/meta/currenciesSupported fiat currencies + hashes
/makers/{address}/historyMaker aggregates + recent activity
/takers/{address}/historyTaker aggregates + recent activity
best practices
rate limits
x402 and paid API keys: 180 rpm (analytics), 300 rpm (explorer). Free tier: 60/120 rpm.
Check X-RateLimit-Remaining header. Back off when approaching 0.
error handling
All errors return { error: { status, code, message } }. Key codes: invalid_api_key, rate_limited, credits_exhausted, invalid_range.
On 429 (rate limited): wait until X-RateLimit-Reset seconds elapse.
On 402 (payment required): this is the x402 flow, not an error. Build payment and retry.
pagination
Most list endpoints accept limit (max: 200) and offset. Default limit varies by endpoint (50-100).
Paginate until the returned array is shorter than the limit.
caching
Cache /meta/platforms and /meta/currencies — they rarely change.
Analytics data updates every 30 minutes. Polling more frequently wastes credits.
Orderbook and market data are real-time — poll as needed within rate limits.
timestamps
All timestamp parameters accept unix seconds, unix milliseconds, or ISO 8601 strings. Addresses are case-insensitive.
tooling & resources
llms.txt
Complete endpoint reference optimized for LLM context windows. Include this file in your agent's system prompt.
OpenAPI 3.1 spec
Machine-readable API schema. Use for SDK generation, request validation, and type-safe clients.
Developer Portal
Manage API keys, buy credits, and test endpoints interactively.
x402 Protocol
Client libraries for TypeScript, Python, and more. Build payment payloads for pay-per-request access.
agent skills
Install Peer Agent Skills for direct protocol access from Claude Code, Cursor, or any AgentSkills runtime:
cp -r skills/analyze-peer-protocol .claude/skills/analyze-peer-protocol export PEERLYTICS_API_KEY=pk_live_your_key_here
/peerlytics:analytics MTDProtocol volume, deposits, trends/peerlytics:explorer 0x...Look up addresses, deposits, intents/peerlytics:leaderboardTop makers and takers/peerlytics:market GBPRates, liquidity, spreads/peerlytics:activityRecent protocol eventswhich endpoint should i use?
What's the current best rate to buy USDC with GBP?
/orderbook?currency=GBP — check bestRate and compare against fxMidRate
How much volume has the protocol done this month?
/analytics/summary for a quick number, or /analytics/period?range=mtd for full breakdown
What has a specific wallet address been doing?
/explorer/address/{address} for combined view, or /explorer/maker/{address} for maker-specific stats
Are there any active deposits accepting buys on Revolut?
/deposits?platform=revolut&accepting=true&status=ACTIVE
Who are the top liquidity providers?
/analytics/leaderboard?limit=10
What payment platforms and currencies are supported?
/meta/platforms and /meta/currencies — cache these