Verify a signed KAIOS receipt

Start with the signed envelope

Send exactly three envelope fields: signature, payload_string, and payload. The payload carries issuer, issued_at, and disclosed_fields; ciphertext_bundle is explicitly optional opaque data.

{
  "signature": "a2a840955190e68e1801646322b7abfdd54fb70b30ac9e23a4d1d777331e3225b20abee94c6e6846718cfe4f846ee16b51e450ae6fc7f9189004fcb4de74da01",
  "payload_string": "{\"issuer\":\"kaios.automa8.ai\",\"issued_at\":\"2026-07-24T12:00:00Z\",\"disclosed_fields\":{\"task\":\"undercollateralized-lending\",\"loan_size_usd\":75000}}",
  "payload": {
    "issuer": "kaios.automa8.ai",
    "issued_at": "2026-07-24T12:00:00Z",
    "disclosed_fields": {
      "task": "undercollateralized-lending",
      "loan_size_usd": 75000
    }
  }
}

Serialize the payload, then sign

This example uses JSON.stringify(payload) as its payload_string. The verifier checks the exact supplied UTF-8 bytes and parses the JSON; the parsed value must equal the structured payload. The issuer may choose another serialization, including different whitespace or object key order.

The displayed fixture requires its matching TEST ONLY public key, which is public in discovery; its private key is not included. For your own receipts, load your issuer-provided Ed25519 private key and configure the verifier with its matching public key. The PEM file path below is an example input; key delivery and storage belong to the issuer.

const crypto = require('node:crypto');
const fs = require('node:fs');

const payload = {
  "issuer": "kaios.automa8.ai",
  "issued_at": "2026-07-24T12:00:00Z",
  "disclosed_fields": {
    "task": "undercollateralized-lending",
    "loan_size_usd": 75000
  }
};
const payloadString = JSON.stringify(payload);
const privateKey = crypto.createPrivateKey(fs.readFileSync('issuer-private-key.pem'));
const signature = crypto.sign(
  null,
  Buffer.from(payloadString, 'utf8'),
  privateKey
).toString('hex'); // lowercase hexadecimal

const envelope = { signature, payload_string: payloadString, payload };
console.log(JSON.stringify(envelope, null, 2));

Run this example with node sign-and-envelope.js > envelope.json to save its JSON output for the verification request below.

The issuer’s private key must correspond to the verifier deployment’s configured KAIOS_ISSUER_PUBLIC_KEY. Keep the private key on the issuer side.

POST the envelope to a local verifier

The page and the GET discovery document require no external credentials. A successful 200 response requires the verifier to have the matching KAIOS_ISSUER_PUBLIC_KEY configured. This TEST ONLY fixture is for local/test use.

VERIFY_URL="${VERIFY_URL:-http://localhost:3000/api/kaios/verify}"
curl -X POST "$VERIFY_URL" \
  -H "Content-Type: application/json" \
  -d '{
  "signature": "a2a840955190e68e1801646322b7abfdd54fb70b30ac9e23a4d1d777331e3225b20abee94c6e6846718cfe4f846ee16b51e450ae6fc7f9189004fcb4de74da01",
  "payload_string": "{\"issuer\":\"kaios.automa8.ai\",\"issued_at\":\"2026-07-24T12:00:00Z\",\"disclosed_fields\":{\"task\":\"undercollateralized-lending\",\"loan_size_usd\":75000}}",
  "payload": {
    "issuer": "kaios.automa8.ai",
    "issued_at": "2026-07-24T12:00:00Z",
    "disclosed_fields": {
      "task": "undercollateralized-lending",
      "loan_size_usd": 75000
    }
  }
}'

const envelope = require('./envelope.json');

async function verifyReceipt() {
  const verifyUrl = process.env.VERIFY_URL || 'http://localhost:3000/api/kaios/verify';
  const response = await fetch(verifyUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(envelope)
  });
  const result = await response.json();

  console.log('HTTP status:', response.status);
  console.log(JSON.stringify(result, null, 2));
}

verifyReceipt().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The outer envelope has signature (a 128-character hex Ed25519 signature), payload_string (the exact UTF-8 bytes signed), and payload (the structured receipt with issuer, issued_at, and disclosed_fields). Optional ciphertext_bundle is included in the payload equality check but is not returned. A successful response includes ok, valid, issuer, issued_at, and disclosed_fields; non-2xx responses return the documented error JSON.

Use the disclosed result

On 200, the endpoint returns exactly the fields below. disclosed_fields is the signed structured disclosure; the verifier does not infer anything beyond it.

{
  "ok": true,
  "valid": true,
  "issuer": "string",
  "issued_at": "ISO-8601 string",
  "disclosed_fields": "object"
}

Verification is an attestation, not an interpretation

If you are working with sealed or encrypted receipt data, read the FHE workflow to understand how ciphertext stays private during agent computation and how commitments connect back to verification.

The endpoint is stateless and publishes the same live contract at https://automa-labs-ai.polsia.app/api/kaios/verify. Use the full contract reference when you need the complete discovery document.