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 wallet)
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

Add compliance-aware data access to your agent in 3 lines:

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

Header	Required	Description
`x-agent-id`	Yes	Your ERC-8004 agent ID
`x-provider-id`	Yes	Provider you're accessing
`x-tier-id`	Optional	Specific pricing tier (defaults to provider base price)

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.

How tiers flow through the system

Agent sends x-tier-id: 2 header to the x402 server
x402 server checks tier-specific compliance: checkTierCompliance(agentId, providerId, tierId)
x402 server reads tier-specific price: getTierPrice(providerId, tierId)
Agent pays the tier price via EIP-3009
After settlement, x402 server forwards the request to the provider's registered endpoint URL, passing all identity headers (x-agent-id, x-provider-id, x-tier-id)
The provider's API reads x-tier-id to determine what data/access level to serve

Each tier can have independent compliance rules that override the provider defaults. For example, a "Premium" tier might require manual approval and OFAC screening, while a "Basic" tier inherits the provider's default rules.

Listing available tiers

Agents can query available tiers for a provider without authentication:

GET https://kya-x402-server.solitary-voice-36e0.workers.dev/api/providers/1/tiers

Response:
{
  "providerId": 1,
  "tiers": [
    { "id": 0, "name": "Standard", "priceFormatted": "$0.0001", "active": true },
    { "id": 1, "name": "Premium", "priceFormatted": "$0.0100", "active": true }
  ]
}

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 via the KYA Dashboard
Link a Self.xyz passport proof (ZK, no PII shared) — scan the QR code with the Self app
Fund your wallet with USDC on Celo Mainnet (requests cost as little as $0.0001)

Denial Reasons

If compliance fails, the server returns 403 with a reason code:

Code	Reason	Meaning
0	None	Compliant — all checks passed
1	AgentNotRegistered	No ERC-8004 identity found
2	NoSelfAttestation	No passport proof linked to agent
3	CountryExcluded	Nationality is on provider's exclusion list
4	AgeTooLow	Below provider's minimum age requirement
5	OfacSanctioned	OFAC sanctions check failed
6	ManualApprovalRequired	Tier requires explicit provider approval for this agent

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, IDs auto-assigned
Tiered pricing — per-tier compliance overrides
Manual tier approval — providers whitelist specific agents per tier
Agent ownership verification — payer must own the claimed ERC-8004 agent
UUPS Upgradeable — contract upgradeable via OpenZeppelin proxy
OFAC override — owner can correct false positives
Replay protection — nullifier tracking prevents proof reuse

x402 MCP Server (for AI Agents like Claude)

KYA ships with a custom x402 MCP server that exposes two tools to any MCP-compatible AI agent (Claude Desktop, etc.):

x402_fetch — Make HTTP requests with automatic x402 payment. Accepts url, method, headers, and body. Handles 402 → EIP-3009 payment → retry automatically.
x402_wallet_info — Returns the configured wallet address and chain info.

Example prompt for your AI agent

Use the x402_fetch tool to GET https://kya-x402-server.solitary-voice-36e0.workers.dev/api/eu-market-data with headers x-agent-id: 2395, x-provider-id: 1, x-tier-id: 0

Claude Desktop configuration

{
  "mcpServers": {
    "x402": {
      "command": "node",
      "args": ["<path-to>/x402-mcp/dist/index.js"],
      "env": {
        "X402_PRIVATE_KEY": "0x...",
        "RPC_URL": "https://forno.celo.org"
      }
    }
  }
}

The X402_PRIVATE_KEY must be the private key of the wallet that owns the ERC-8004 agent. The MCP server uses Celo Mainnet with USDC payments.

Deployed System

Component	URL / Address
Dashboard	kya-dashboard.pages.dev
x402 Server	kya-x402-server.solitary-voice-36e0.workers.dev
KYA Contract (Proxy)	0x425372FDBD799870fb97F3f126aEEb078BA5FF04
ERC-8004 Registry	0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
Self Hub V2	0xe57F4773bd9c9d8b6Cd70431117d353298B9f5BF
USDC (Celo)	0xcebA9300f2b948710d2653dD7B07f33A8B32118C

Tech Stack

Layer	Technology
Smart Contract	Solidity 0.8.28, Foundry, UUPS proxy (OpenZeppelin 5.4)
Identity	Self.xyz SDK, SelfVerificationRoot, ZK passport proofs
Agent Standard	ERC-8004 on Celo Mainnet
Payments	x402 protocol, @x402/fetch, USDC micropayments
Backend	Hono on Cloudflare Workers
Frontend	React + Vite + Tailwind + wagmi + RainbowKit

Resources

x402 MCP Server Documentation — Coinbase Developer Platform x402 protocol reference
x402 Protocol — HTTP-native micropayments specification
Self.xyz Docs — ZK passport proof integration
Self Contract Integration — Solidity integration guide
ERC-8004 Spec — Agent identity standard
Celo Developer Docs

KYA — Know Your Agent | Compliance middleware for the agentic economy | Built on Celo