Ananke TCode

Payload generation

How Ananke TCode payloads are generated, what they contain, and how they encode document metadata into a compact binary format suitable for DataMatrix barcodes.

Overview

When you stamp a document, Ananke Labs generates a binary payload that encodes document metadata, a content hash, and a cryptographic signature. This payload is rendered as a DataMatrix barcode and embedded into the PDF.

The payload is designed to be compact (to fit in a printable barcode) while carrying enough information for both online and offline verification.

What a payload contains

Field	Description
Header	Protocol version, issuer code (6-char tenant reference), and document type.
Content hash	SHA-256 hash of the document content for integrity verification.
Metadata	Document reference, issue timestamp, and key fields from the document.
Signature	ECDSA signature over the hash and metadata, verifiable with the issuer's public key.

Generation flow

You send a stamp request with the PDF and metadata.
Ananke Labs computes the content hash of the PDF.
The platform builds the payload — header, hash, metadata, and signature.
The payload is encoded into a DataMatrix barcode.
The barcode is rendered and placed on the PDF at the configured position.
The stamped PDF is stored and a reference is returned.

API usage

Payload generation is automatic when using the stamp endpoint. You don't generate payloads separately — the stamp request handles everything:

curl — Stamp request (payload generated automatically)

curl -X POST https://api.anankelabs.net/v1/tcode/stamps \
  -H "x-api-key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice #1234",
    "documentTypeCode": "INV",
    "pdf": "<base64-encoded PDF>"
  }'

SDK usage

SDK — Stamp (includes payload generation)

import { readFileSync } from "node:fs";

const stamp = await client.tcode.documents.stamp({
  name:             "Invoice #1234",
  documentTypeCode: "INV",
  pdf:              readFileSync("./invoice.pdf"),
});

// The returned stamp includes the generated reference
console.log(stamp.reference);  // "TCR-XXXX"

Payload structure

The binary payload follows a structured wire format. Developers generally don't need to parse this directly — the verification API handles decode and validation. For those building custom scanners, the high-level structure is:

Payload wire format (simplified)

┌──────────────────────────────────────┐
│ Header (version, issuer, doc type)   │
├──────────────────────────────────────┤
│ Content hash (SHA-256, 32 bytes)     │
├──────────────────────────────────────┤
│ Metadata (reference, timestamp, ...) │
├──────────────────────────────────────┤
│ Signature (ECDSA)                    │
└──────────────────────────────────────┘

The verification endpoint accepts the raw payload and returns a structured result without requiring the verifier to understand the wire format.

Next steps

Stamping PDFs — Place the barcode into a document.
Verification & scans — Verify stamped documents.
Guide: Generate an Ananke TCode — End-to-end tutorial.