Verify Endpoint | KYA Chain

Overview

The Verification API provides fast, off-chain verification of AI agent identities. The API aggregates data from multiple on-chain registries (Identity, Reputation, Validation, TrustVault, Organization) and returns a comprehensive trust profile.

Base URL: https://api.kyachain.xyz

Health Endpoints

GET /livez

Liveness check. Returns 200 if the API is running.

curl https://api.kyachain.xyz/livez

GET /readyz

Readiness check. Returns 200 if the API is ready to serve requests (Redis and RPC connections healthy).

curl https://api.kyachain.xyz/readyz

POST /verify

Primary verification method using API keys.

Verify an agent's identity using an API key. This is the recommended method for production applications.

Request

POST https://api.kyachain.xyz/verify
Content-Type: application/json

{
  "apiKey": "kya_live_v1_<64-char-hex>",
  "agentId": "42",        // optional - defaults to key's agent
  "origin": "https://myapp.com"  // optional - endpoint mismatch check
}

Field	Type	Required	Description
`apiKey`	string	Yes	API key in format `kya_live_v1_[a-f0-9]{64}`
`agentId`	string	No	Agent ID to verify (defaults to the agent that owns the API key)
`origin`	string	No	Your application's origin URL for endpoint mismatch detection

Response (200 OK)

{
  "valid": true,
  "agentId": "42",
  "owner": "0x3CDA80d87cDde4612C9b66B657d45055Fa03Ce99",
  "trustTier": 2,
  "stakedAmount": "10000000000000000000000",
  "reputation": {
    "totalScore": "15",
    "feedbackCount": 3,
    "averageRating": 5.0
  },
  "validation": {
    "count": 1,
    "latestPassed": true,
    "latestEvidence": "Security audit passed",
    "latestValidator": "0x..."
  },
  "metadataURI": "ipfs://QmAgentMetadata...",
  "timestamp": 1707408000,
  "endpointMismatch": false,
  "organizations": [
    {
      "orgId": "1",
      "name": "Nethara Labs",
      "verified": true
    }
  ]
}

Response Fields

Field	Type	Description
`valid`	boolean	Always `true` on 200 responses (agent exists and key is valid)
`agentId`	string	The verified agent ID
`owner`	string	Ethereum address that owns the agent NFT
`trustTier`	number	Trust tier 0-4 based on staked LABS
`stakedAmount`	string	Amount of WLABS staked (in wei, as string for BigInt safety)
`reputation.totalScore`	string	Sum of all feedback scores (can be negative)
`reputation.feedbackCount`	number	Number of feedback submissions
`reputation.averageRating`	number \| null	Average rating, or null if no feedback
`validation.count`	number	Number of validation submissions
`validation.latestPassed`	boolean \| null	Latest validation result, or null if no validations
`validation.latestEvidence`	string \| null	Latest validation evidence
`validation.latestValidator`	string \| null	Address of latest validator
`metadataURI`	string	Agent metadata URI (typically IPFS)
`timestamp`	number	Unix timestamp of verification
`endpointMismatch`	boolean	True if `origin` param doesn't match declared endpoint in API key
`organizations`	array	Organizations the agent belongs to

POST /verify/signature

Legacy/advanced verification method using EIP-712 signatures.

Verify an agent using an EIP-712 signature from the agent owner. Useful for serverless or peer-to-peer verification where managing API keys is impractical.

Note: POST /verify with API keys is the recommended method for production. This endpoint is available for advanced use cases.

Request

POST https://api.kyachain.xyz/verify/signature
Content-Type: application/json

{
  "agentId": "42",
  "signature": "0x<130-hex-chars>",
  "nonce": "1",
  "timestamp": 1707408000
}

Field	Type	Required	Description
`agentId`	string	Yes	Agent ID as numeric string (BigInt serialization)
`signature`	string	Yes	EIP-712 signature (65 bytes = 0x + 130 hex chars)
`nonce`	string	Yes	Random nonce as numeric string (prevents replay attacks)
`timestamp`	number	Yes	Unix timestamp in seconds (must be recent)

EIP-712 Signature

The signature must be created using the EIP-712 typed data standard with these parameters:

const domain = {
  name: 'KYA Verification',
  version: '1',
  chainId: 8004,
  verifyingContract: '0xA1393CB409E2fE5573C0840189622aA0e33947b2', // IdentityRegistry
};

const types = {
  Verification: [
    { name: 'agentId', type: 'uint256' },
    { name: 'nonce', type: 'uint256' },
    { name: 'timestamp', type: 'uint256' },
  ],
};

const message = {
  agentId: 42n,
  nonce: 1n,
  timestamp: 1707408000n,
};

// Sign with viem
const signature = await walletClient.signTypedData({
  domain,
  types,
  primaryType: 'Verification',
  message,
});

const response = await fetch('https://api.kyachain.xyz/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apiKey: 'kya_live_v1_abc123...',
    agentId: '42',
    origin: 'https://myapp.com',
  }),
});

const data = await response.json();

if (data.valid) {
  console.log('Agent verified!');
  console.log('Trust tier:', data.trustTier);
  console.log('Staked amount:', data.stakedAmount);
} else {
  console.error('Verification failed');
}

TypeScript (EIP-712 Signature)

Verify agent with signature

import { createWalletClient, http } from 'viem';
import { kyaChain } from './chains';

const walletClient = createWalletClient({
  chain: kyaChain,
  transport: http('https://rpc.kyachain.xyz'),
});

// Create EIP-712 signature
const agentId = 42n;
const nonce = BigInt(Math.floor(Math.random() * 1e18));
const timestamp = BigInt(Math.floor(Date.now() / 1000));

const signature = await walletClient.signTypedData({
  domain: {
    name: 'KYA Verification',
    version: '1',
    chainId: 8004,
    verifyingContract: '0xA1393CB409E2fE5573C0840189622aA0e33947b2',
  },
  types: {
    Verification: [
      { name: 'agentId', type: 'uint256' },
      { name: 'nonce', type: 'uint256' },
      { name: 'timestamp', type: 'uint256' },
    ],
  },
  primaryType: 'Verification',
  message: { agentId, nonce, timestamp },
});

// Verify with API
const response = await fetch('https://api.kyachain.xyz/verify/signature', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: agentId.toString(),
    signature,
    nonce: nonce.toString(),
    timestamp: Number(timestamp),
  }),
});

const data = await response.json();
console.log('Verification result:', data);

Rate Limiting

The /verify endpoints are rate limited based on the agent's trust tier:

Tier	Rate Limit
0 (Unverified)	Blocked (403)
1 (Bronze)	1 request/minute
2 (Silver)	16 requests/minute
3 (Gold)	166 requests/minute
4 (Diamond)	2700 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: Maximum requests allowed per window
X-RateLimit-Remaining: Requests remaining in current window
Retry-After: Seconds to wait before retrying (on 429 errors)

See the Error Reference for rate limiting error details.

Overview

Health Endpoints

GET /livez

GET /readyz

POST /verify

Request

Response (200 OK)

Response Fields

POST /verify/signature

Request

EIP-712 Signature

Response

Usage Examples

TypeScript (API Key)

TypeScript (EIP-712 Signature)

Rate Limiting

On this page