KYA API Documentation

Pre-credentialing verification layer for AI agents in agentic commerce

Integration Flow

[AI Agent] → [ACP Checkout Request with kya_id] → [Merchant]

↓

[Query /v1/verify with kya_id]

↓

[Trust Score + Attestations + Behavior]

↓

[Accept/Review/Decline Decision]

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

Who Uses This API

Agent Operators

Merchants

Query trust signals before accepting agent transactions

AI Platforms

Embed KYA IDs in agent requests for seamless verification

Authentication

Operator endpoints require your Operator API key. Merchant endpoints require your Merchant API key.

X-KYA-Api-Key: kya_op_live_1234567890abcdef...  // For operators
X-KYA-Merchant-Key: kya_mc_live_abcdef1234567890...  // For merchants

Get your API keys from the dashboard after registration at /get-verified

API Endpoints

Operator Registration

Register Operator

POST /v1/operators

Request Body:

{
  "legal_name": "Acme AI Corp",
  "dba_name": "Acme Agents",
  "incorporation_country": "US",
  "incorporation_state": "DE",
  "tax_id": "12-3456789",
  "website": "https://acme-ai.com",
  "contact_email": "compliance@acme-ai.com",
  "primary_contact_name": "Jane Doe",
  "primary_contact_email": "jane@acme-ai.com"
}

Response (201):

{
  "operator_id": "kya_op_01HX5N2CJKRQVZW8",
  "api_key": "kya_op_live_1234567890abcdef...",
  "status": "pending_verification",
  "message": "Operator registered. KYB verification pending.",
  "next_steps": [
    "Upload KYB documents at /operators/{id}/verification",
    "Wait for verification (typically 2-3 business days)",
    "Begin registering agents once verified"
  ]
}

Important: Save your API key immediately. It will only be shown once and cannot be retrieved later.

Get Operator Details

GET /v1/operators/{operator_id}

Retrieve operator information and verification status.

Headers:

X-KYA-Api-Key: kya_op_live_1234567890abcdef...

Response (200):

{
  "operator_id": "kya_op_01HX5N2CJKRQVZW8",
  "legal_name": "Acme AI Corp",
  "status": "verified",
  "verification_tier": "standard",
  "verified_at": "2025-01-15T10:30:00Z",
  "total_agents": 12,
  "active_agents": 10
}

HTTP Response Codes

Code	Meaning	Description
`200`	OK	Request successful
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error, contact support

Rate Limits

Plan	Verifications/Month	Burst Limit	Price
Starter	10,000	100/minute	Free
Growth	100,000	1,000/minute	$99/month
Enterprise	Unlimited	Custom	Contact sales

Rate limit headers included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

SDKs & Integration

JavaScript/TypeScript

Coming soon

npm install @knowyouragent/sdk

import { KYA } from '@knowyouragent/sdk';

const kya = new KYA({
  merchantKey: 'kya_mc_live_...'
});

// Verify agent
const result = await kya.verify({
  kya_id: 'kya_agent_01HX...',
  amount_cents: 4999
});

if (result.recommendation.action === 'accept') {
  // Process transaction
}

cURL Examples

Direct HTTP requests

# Verify an agent
curl -X POST https://api.knowyouragent.xyz/v1/verify \
  -H "X-KYA-Merchant-Key: kya_mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kya_id": "kya_agent_01HX...",
    "transaction_context": {
      "amount_cents": 4999,
      "currency": "USD"
    }
  }'

Need Help?

Our team is here to help you integrate KYA into your agentic commerce platform.

Contact API Support Get Started