KYA — Know Your Agent

Compliance middleware for the agentic economy

KYA binds Self.xyz ZK passport proofs to ERC-8004 agent identities on Celo. Data providers register compliance rules on-chain. Compliant agents automatically pay via x402 USDC micropayments. No KYC portal, no middleman — just math.

The Problem

AI agents need to access paid data APIs. Data providers have regulatory requirements: jurisdiction restrictions, age verification, sanctions screening. There's no standard way for an agent to prove compliance. Providers either block all agents or skip compliance entirely.

Architecture

Agent CLI                    Cloudflare Workers              Celo Mainnet
+-------------+     HTTP     +--------------------+    RPC    +------------------+
| Agent Wallet |------------>| x402 Server        |--------->| KYA Contract     |
| (USDC)       |             |                    |          | (UUPS Proxy)     |
|              |             | 1. Compliance Check|          |                  |
| @x402/fetch  |             | 2. 402 Payment Req |          | Self.xyz Hub     |
| auto-pays    |<------------|  3. Verify+Settle   |          | ERC-8004         |
|              |    Data     | 4. Serve Data      |          | USDC             |
+-------------+             +--------------------+          +------------------+

How It Works

Provider registers compliance rules (min age, excluded countries, OFAC screening) — permissionless, auto-assigned ID
Provider defines pricing tiers — each tier has a name, price, and optional per-tier compliance overrides
Agent registers an ERC-8004 identity on Celo
Agent links a Self.xyz passport proof — ZK, no personal data leaves the phone
Agent requests data via x402 endpoint with headers: x-agent-id, x-provider-id, x-tier-id (optional)
Server verifies agent ownership (ERC-8004.ownerOf == payer)
Server checks tier compliance on-chain: checkTierCompliance(agentId, providerId, tierId)
If tier requires manual approval, checks isTierApproved(providerId, tierId, agentId)
If compliant — 402 Payment Required — agent auto-pays USDC via @x402/fetch
Server settles USDC on Celo, serves data

For Agent Developers — Quick Start

import { wrapFetchWithPayment } from '@x402/fetch';

const paidFetch = wrapFetchWithPayment(fetch, wallet);

const data = await paidFetch('https://kya-x402-server.solitary-voice-36e0.workers.dev/api/data', {
  headers: {
    'x-agent-id': '2395',
    'x-provider-id': '1',
    'x-tier-id': '0',       // optional
  }
});

Required Headers

x-agent-id (required) — Your ERC-8004 agent ID
x-provider-id (required) — Provider you're accessing
x-tier-id (optional) — Specific pricing tier

Example curl Requests

# Access provider 1 (default tier, base price)
curl -H "x-agent-id: 2395" -H "x-provider-id: 1" https://kya-x402-server.solitary-voice-36e0.workers.dev/api/data

# Access provider 1, specific tier
curl -H "x-agent-id: 2395" -H "x-provider-id: 1" -H "x-tier-id: 2" https://kya-x402-server.solitary-voice-36e0.workers.dev/api/data

Tiered Access

Providers can define multiple pricing tiers, each with its own price and compliance rules. Tiers can require manual approval — the provider must explicitly approve each agent ID before it can access that tier. Use the x-tier-id header to select a tier.

Agent Ownership Verification

During payment settlement, the x402 server verifies that the payer wallet owns the claimed ERC-8004 agent (ownerOf(agentId) == payer). This prevents agent impersonation — you cannot pay on behalf of an agent you do not control.

Prerequisites

Register an ERC-8004 agent identity on Celo
Link a Self.xyz passport proof (ZK, no PII shared)
Fund your wallet with USDC on Celo

Denial Reasons

0 — None (compliant)
1 — AgentNotRegistered
2 — NoSelfAttestation
3 — CountryExcluded
4 — AgeTooLow
5 — OfacSanctioned
6 — ManualApprovalRequired

Key Features

ZK Passport Proofs — nationality, age, OFAC verified without revealing personal data
On-chain compliance — rules stored on Celo, checked per-request, fully auditable
x402 Micropayments — USDC per API call, settled on Celo
Permissionless marketplace — anyone can register as a provider
Tiered pricing with per-tier compliance overrides
Manual tier approval for premium access
Agent ownership verification during payment (prevents impersonation)

Deployed System

Dashboard: kya-dashboard.pages.dev
x402 Server: kya-x402-server.solitary-voice-36e0.workers.dev
KYA Contract (Proxy): 0x425372FDBD799870fb97F3f126aEEb078BA5FF04
ERC-8004 Registry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
USDC (Celo): 0xcebA9300f2b948710d2653dD7B07f33A8B32118C
Full docs: kya-dashboard.pages.dev/#docs

Tech Stack