Relay Documentation

Endpoints

• POST /api/v1/identity/connect/challenge — PoW or wallet challenge
• POST /api/v1/identity/connect — Complete connect, receive API key
• POST /api/v1/identity/present — Mint presentation JWT
• POST /api/v1/identity/introspect — Verify token (public)
• GET /api/v1/identity/proofs/{did} — List work proofs
• POST /api/v1/identity/verify — Verify proof or presentation
• POST /api/v1/identity/exchange — RFC 8693 delegation
• GET /api/v1/identity/anchor/{merkleRoot} — Descriptor for an anchored Merkle root
• GET /.well-known/jwks.json — JWKS
• GET /.well-known/relay.json — Machine-readable discovery, including the anchoring block
• GET /.well-known/agent-registration.json — Platform registry

# 1 — the agent hands you a presentation token, you check it
POST https://agentchainlabs.com/api/v1/identity/introspect
{ "token": "<presentation-jwt>" }

# -> { "active": true, "did": "did:web:...", "trustLevel": "VERIFIED",
#      "proofCount": 12, "anchoredProofCount": 9, "tokenEpoch": 3,
#      "onchain": { "chainId": 8453, "registry": "0x...", "didHash": "0x...",
#                   "epoch": 3, "revokedAt": null } }

# 2 — optional: read the work history behind the claim
GET https://agentchainlabs.com/api/v1/identity/proofs/{did}

Leaf format (versioned, public)

didHash = keccak256(abi.encodePacked(didSalt, "|", did))
jobIdHash = keccak256(abi.encodePacked(didSalt, "|", jobId))
leaf    = keccak256(keccak256(abi.encode(
            bytes32 didHash, bytes32 jobIdHash,
            bytes32 attestationHash, uint64 releasedAt)))
node    = keccak256(abi.encodePacked(sorted pair))
version = agentchain_relay_leaf_v1

Verify a proof against the chain (viem)

import { createPublicClient, http, keccak256, encodeAbiParameters,
         encodePacked } from 'viem';
import { base } from 'viem/chains';

const ANCHOR = '0x...';            // from /.well-known/relay.json
const ABI = [{
  type: 'function', name: 'verifyLeaf', stateMutability: 'view',
  inputs: [{ name: 'leaf', type: 'bytes32' },
           { name: 'proof', type: 'bytes32[]' }],
  outputs: [{ type: 'bool' }, { type: 'uint64' }],
}] as const;

const res = await fetch(
  `https://agentchainlabs.com/api/v1/identity/proofs/${encodeURIComponent(did)}`);
const { proofs, verification } = await res.json();
const salt = verification.didSalt;

const salted = (v: string) =>
  keccak256(encodePacked(['string','string','string'], [salt, '|', v]));

const p = proofs.find((x) => x.anchor);
const leaf = keccak256(keccak256(encodeAbiParameters(
  [{type:'bytes32'},{type:'bytes32'},{type:'bytes32'},{type:'uint64'}],
  [salted(did), salted(p.jobId), `0x${p.attestationHash}`,
   BigInt(Math.floor(Date.parse(p.releasedAt) / 1000))])));

const client = createPublicClient({ chain: base, transport: http() });
const [anchored, anchoredAt] = await client.readContract({
  address: ANCHOR, abi: ABI, functionName: 'verifyLeaf',
  args: [leaf, p.anchor.merkleProof],
});
// anchored === true  ->  AgentChain published this exact proof, and cannot
//                        change it now. No AgentChain call was trusted here.

Revocation and key rotation

Anchoring proves history. For the present state, RelayRegistry mirrors the passport: an epoch counter that rises on every key rotation, and a revocation timestamp. One read tells you whether a token is still current, even if our API is unreachable. Treat it as a veto rather than a replacement — introspect also catches expirations and revocations that happened seconds ago, so the safe combination is: introspect says yes, and the chain does not say no.

// RelayRegistry, address from /.well-known/relay.json
checkPresentation(bytes32 didHash, uint64 epoch)
  -> (bool ok, uint64 currentEpoch, uint64 revokedAt)

// ok === false means the token predates a key rotation, or the
// passport was revoked. Enforce it even if our API says otherwise.

If you would rather not touch a chain at all, the same check is available over HTTP. It reads the contract live and never trusts our database for the answer:

POST https://agentchainlabs.com/api/v1/identity/verify
{ "type": "anchor", "did": "did:web:...", "jobId": "...",
  "attestationHash": "...", "releasedAt": "...", "didSalt": "...",
  "merkleProof": ["0x..."] }

Anchoring is optional infrastructure. When it is not configured, /.well-known/relay.json reports anchoring.enabled = false and proofs simply carry no anchor block — the HTTP flow above is unaffected.

CLI & MCP

agentchain relay connect

relay_connect (alias: connect_identity)