Agent Protocol Reference

// Save as agent-protocol-quickstart.mjs and run from the World Cup app root.
// Requires the local dev server on http://localhost:3001.
import { bytesToHex, hexToBytes } from "viem";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import { secp256k1 } from "@noble/curves/secp256k1";
import { canonicalize } from "./src/lib/crypto/canonical.ts";
import {
  buyerDecrypt,
  buyerUnwrapDek
} from "./src/lib/crypto/ecies.ts";

const BASE = process.env.ACCESSURA_API_BASE ?? "http://localhost:3001/api/v1";
const PACK_ID = "wc-2026-player-status";
const SIGNAL_ID = "sig-wc-2026-player-status-default";
const PRICE = Number(process.env.ACCESSURA_BID_PRICE ?? 100);
const RUN_ID = Math.random().toString(36).slice(2, 8);
const AGENT_ID = process.env.ACCESSURA_AGENT_ID ?? "buyer-agent-" + RUN_ID;
const EXPIRY = new Date(Date.now() + 60 * 60 * 1000).toISOString();

const DOMAIN = {
  name: "WorldcupProtocol",
  version: "1",
  chainId: 8453,
  verifyingContract: "0x0000000000000000000000000000000000000000"
};

const TYPES = {
  AuthChallenge: [
    { name: "challenge_id", type: "string" },
    { name: "agent_id", type: "string" },
    { name: "nonce", type: "string" },
    { name: "expires_at", type: "string" }
  ],
  BidAuthorization: [
    { name: "bid_id", type: "string" },
    { name: "pack_id", type: "string" },
    { name: "signal_id", type: "string" },
    { name: "signal_scope", type: "string" },
    { name: "price", type: "string" },
    { name: "buyer_payment_address", type: "address" },
    { name: "buyer_signing_key", type: "address" },
    { name: "buyer_encryption_pubkey", type: "string" },
    { name: "delegation_id", type: "string" },
    { name: "window_id", type: "string" },
    { name: "nonce", type: "string" },
    { name: "expiry", type: "string" }
  ],
  SessionDelegation: [
    { name: "delegation_id", type: "string" },
    { name: "owner_wallet", type: "address" },
    { name: "session_key", type: "address" },
    { name: "allowance", type: "string" },
    { name: "scope", type: "string" },
    { name: "expiry", type: "string" },
    { name: "nonce", type: "string" }
  ],
  DeliveryAck: [
    { name: "payment_id", type: "string" },
    { name: "bid_id", type: "string" }
  ]
};

async function api(path, options = {}) {
  const headers = { ...(options.headers ?? {}) };
  if (options.body !== undefined) headers["content-type"] = "application/json";
  if (options.token) headers.authorization = "Bearer " + options.token;

  const response = await fetch(BASE + path, {
    method: options.method ?? "GET",
    headers,
    body: options.body === undefined ? undefined : JSON.stringify(options.body)
  });
  const json = await response.json().catch(() => ({}));
  if (!response.ok && options.throwOnError !== false) {
    throw new Error((options.method ?? "GET") + " " + path + " -> " + response.status + " " + JSON.stringify(json));
  }
  return { status: response.status, json };
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const uncompressedSecp256k1Pubkey = (privateKey) =>
  bytesToHex(secp256k1.getPublicKey(hexToBytes(privateKey), false));

// 1) Generate three buyer keys with viem + @noble.
const paymentPrivateKey = generatePrivateKey();
const signingPrivateKey = generatePrivateKey();
const encryptionPrivateKey = generatePrivateKey();
const payment = privateKeyToAccount(paymentPrivateKey);
const signing = privateKeyToAccount(signingPrivateKey);
const encryptionPubkey = uncompressedSecp256k1Pubkey(encryptionPrivateKey);

console.log("agent_id", AGENT_ID);
console.log("payment_address", payment.address);
console.log("signing_key", signing.address);
console.log("encryption_pubkey", encryptionPubkey);

// 2) Register the identity.
await api("/agents/identity", {
  method: "POST",
  body: {
    action: "register_identity",
    agent_id: AGENT_ID,
    agent_name: AGENT_ID,
    role: "buyer",
    payment_address: payment.address,
    signing_key: signing.address,
    encryption_pubkey: encryptionPubkey
  }
});

// 3) Challenge-response auth.
const challenge = (await api("/auth/token", {
  method: "POST",
  body: { agent_id: AGENT_ID, action: "challenge" }
})).json.challenge;

const authSignature = await signing.signTypedData(challenge.sign_payload);
const token = (await api("/auth/token", {
  method: "POST",
  body: {
    agent_id: AGENT_ID,
    challenge_id: challenge.challenge_id,
    signature: authSignature
  }
})).json.token;

// 4) Fund the buyer and register an owner-signed session delegation.
await api("/wallet", {
  method: "POST",
  token,
  body: { action: "deposit", agent_id: AGENT_ID, amount: 1000 }
});

const delegationId = "deleg-" + RUN_ID;
const delegationScope = { can_bid: true };
const delegationSignature = await payment.signTypedData({
  domain: DOMAIN,
  types: { SessionDelegation: TYPES.SessionDelegation },
  primaryType: "SessionDelegation",
  message: {
    delegation_id: delegationId,
    owner_wallet: payment.address,
    session_key: signing.address,
    allowance: String(50000),
    scope: canonicalize(delegationScope),
    expiry: EXPIRY,
    nonce: "dn-" + RUN_ID
  }
});

await api("/agents/identity", {
  method: "POST",
  token,
  body: {
    action: "register_delegation",
    owner_wallet: payment.address,
    session_key: signing.address,
    allowance: 50000,
    scope: delegationScope,
    expiry: EXPIRY,
    nonce: "dn-" + RUN_ID,
    delegation_id: delegationId,
    signature: delegationSignature
  }
});

// 5) Sign and submit BidAuthorization.
const bidId = "bid-" + RUN_ID;
const rawAuthorization = {
  bid_id: bidId,
  pack_id: PACK_ID,
  signal_id: SIGNAL_ID,
  signal_scope: {},
  price: PRICE,
  buyer_payment_address: payment.address,
  buyer_signing_key: signing.address,
  buyer_encryption_pubkey: encryptionPubkey,
  delegation_id: delegationId,
  window_id: "w",
  nonce: "bn-" + RUN_ID,
  expiry: EXPIRY
};

const bidSignature = await signing.signTypedData({
  domain: DOMAIN,
  types: { BidAuthorization: TYPES.BidAuthorization },
  primaryType: "BidAuthorization",
  message: {
    ...rawAuthorization,
    signal_scope: canonicalize(rawAuthorization.signal_scope),
    price: String(rawAuthorization.price)
  }
});

await api("/packs/" + PACK_ID + "/bid", {
  method: "POST",
  token,
  body: {
    agent_id: AGENT_ID,
    bid_price: PRICE,
    signal_id: SIGNAL_ID,
    authorization: { ...rawAuthorization, signature: bidSignature }
  }
});

// 6) Settle until the hold exists.
let hold = null;
for (let attempt = 0; attempt < 25; attempt += 1) {
  await api("/packs/" + PACK_ID + "/settle", {
    method: "POST",
    token,
    body: { agent_id: AGENT_ID, signal_id: SIGNAL_ID }
  });
  const holdResponse = await api("/holds?bid_id=" + encodeURIComponent(bidId), {
    token,
    throwOnError: false
  });
  hold = holdResponse.json.hold ?? null;
  if (hold) break;
  await sleep(1200);
}
if (!hold) throw new Error("hold was not created for " + bidId);

// 7) Get the buyer claim and request key release.
const claims = (await api("/claims", { token })).json.claims ?? [];
const claim = claims.find((item) => item.bid_id === bidId);
if (!claim) throw new Error("claim not found for " + bidId);

const keyRelease = (await api("/mock-seller/claims/" + claim.claim_id + "/key-release", {
  token,
  headers: {
    "accessura-claim": claim.claim_header,
    "idempotency-key": "kr-" + RUN_ID
  }
})).json;

// 8) Decrypt ECIES delivery.
const broker = JSON.parse(Buffer.from(keyRelease.wrapped_key, "base64url").toString("utf8"));
const plaintext = buyerDecrypt(
  broker,
  keyRelease.delivery_artifact_b64,
  encryptionPrivateKey
);
const delivery = JSON.parse(plaintext.toString("utf8"));
console.log("delivery", delivery);

// Optional integrity dispute branch. Use this instead of DeliveryAck when checks fail.
if (process.env.ACCESSURA_OPEN_DISPUTE === "1") {
  const revealedDek = buyerUnwrapDek(broker, encryptionPrivateKey);
  const dispute = (await api("/disputes/protocol", {
    method: "POST",
    token,
    body: {
      receipt_token: keyRelease.delivery_receipt.receipt_id,
      revealed_dek: revealedDek,
      ciphertext_b64: keyRelease.delivery_artifact_b64
    }
  })).json;
  console.log("dispute", dispute);
  process.exit(0);
}

// 9) Read the receipt token and sign DeliveryAck to release the hold.
const bidState = (await api(
  "/packs/" + PACK_ID + "/bid?agent_id=" + encodeURIComponent(AGENT_ID) +
    "&signal_id=" + encodeURIComponent(SIGNAL_ID),
  { token }
)).json;
const receiptToken = bidState.your_receipt?.receipt_token;
if (!receiptToken) throw new Error("receipt token not found");

const ackSignature = await signing.signTypedData({
  domain: DOMAIN,
  types: { DeliveryAck: TYPES.DeliveryAck },
  primaryType: "DeliveryAck",
  message: { payment_id: "hold-" + bidId, bid_id: bidId }
});

const ack = (await api("/receipts/" + receiptToken + "/ack", {
  method: "POST",
  token,
  body: {
    agent_id: AGENT_ID,
    buyer_ack_signature: ackSignature
  }
})).json;

console.log("ack", ack);
console.log("complete", { agent_id: AGENT_ID, bid_id: bidId, receipt_token: receiptToken });