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.

api key header
x-api-key: pk_live_your_key_here

x402 pay-per-request flow

1

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.

2

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.

3

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.

typescript — using @x402/evm
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");
python — using requests
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 libraries

x402 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.

full orderbook
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.

Market IntelligenceCurrent state of P2P liquidity and rates
GET
/orderbook

Full orderbook with rate levels, stats, 24h activity, FX mid-rates

params: currency, platform, minSize

GET
/market/summary

Rates and liquidity by platform/currency

params: platform, currency, includeRates, limit

AnalyticsProtocol metrics and trends
GET
/analytics/summary

Top-level protocol summary

GET
/analytics/period

Full analytics for a time range

params: range, start, end, currency, verifier

GET
/analytics/{slice}

Specific slice (overview, liquidity, volume, activity, flows, performance)

params: same as period

GET
/analytics/leaderboard

Top makers and takers (paginated)

params: limit, offset

GET
/analytics/attribution

Intent attribution breakdown

ExplorerLook up specific deposits, intents, and addresses
GET
/explorer/search

Search by hash, address, or deposit ID

params: q (required), type, role, limit, offset

GET
/explorer/deposit/{id}

Deposit details + linked intents

params: limit, offset

GET
/explorer/intent/{hash}

Intent details + fulfillment info

GET
/explorer/address/{address}

Address deposits + intents

params: limit, offset

GET
/explorer/maker/{address}

Maker portfolio and performance

Data QueriesFilter deposits and intents directly
GET
/deposits

Query deposits (at least one filter required)

params: depositor, delegate, platform, currency, status, accepting, limit

GET
/intents

Query intents (at least one filter required)

params: owner, recipient, verifier, depositId, status, limit

ActivityProtocol events feed
GET
/activity

Recent events (deposits + intents)

params: type, intentHash, depositId, address, since, limit

GET
/activity/stream

SSE for real-time events (API key only)

params: type, since, limit, intervalMs

ReferencePlatform and currency metadata, address history
GET
/meta/platforms

Supported payment platforms + method hashes

GET
/meta/currencies

Supported fiat currencies + hashes

GET
/makers/{address}/history

Maker aggregates + recent activity

GET
/takers/{address}/history

Taker 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

agent skills

Install Peer Agent Skills for direct protocol access from Claude Code, Cursor, or any AgentSkills runtime:

install
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 events

which endpoint should i use?

Q:

What's the current best rate to buy USDC with GBP?

/orderbook?currency=GBP — check bestRate and compare against fxMidRate

Q:

How much volume has the protocol done this month?

/analytics/summary for a quick number, or /analytics/period?range=mtd for full breakdown

Q:

What has a specific wallet address been doing?

/explorer/address/{address} for combined view, or /explorer/maker/{address} for maker-specific stats

Q:

Are there any active deposits accepting buys on Revolut?

/deposits?platform=revolut&accepting=true&status=ACTIVE

Q:

Who are the top liquidity providers?

/analytics/leaderboard?limit=10

Q:

What payment platforms and currencies are supported?

/meta/platforms and /meta/currencies — cache these