Integration overview

Where your product stops and Tokenistry starts, which service owns which decision, and the small number of things worth getting right early.

You build above the API

Your product holds the things that make it yours: subscriptions, workflow, investor experience, whatever your business actually is. Tokenistry holds the parts that are the same at every issuer and expensive to get wrong — the ledger, compliance enforcement, chain execution and reconciliation.

The boundary is the HTTP API, and it is deliberately the only boundary. You never depend on our internals, so an upgrade on our side cannot break your product.

your product
     │  HTTP, versioned
     ├── tokenization    issues, freezes, seizes; signs, never pays gas
     ├── transaction     pays gas, holds no authority
     ├── reconciliation  effective ownership, FIFO lots, provenance
     ├── indexer         normalized chain events
     └── registrar       deterministic deployment
                │
           EVM network

Which service to call

The one that surprises people: ownership questions go to reconciliation, not to the chain. A wallet balance is a number; effective ownership is a position with lineage, and only reconciliation has it.

Four things to get right early

Treat writes as asynchronous

A write that ends in a chain transaction is accepted, not completed. The response tells you it was accepted; confirmation arrives later. Model that in your product from the first day rather than retrofitting it after the first reorg.

Send an idempotency key on every write

Derive it from something stable in your own domain — a subscription id, an instruction reference — rather than a random value per attempt. A random key makes a retry a second transaction, which is precisely what the header exists to prevent.

Let the ledger be the source of truth for positions

Mirroring balances into your own database creates a second answer that has to be reconciled with the first. If you need positions locally for performance, cache them with an obvious expiry and never let the cache decide anything.

Decide where signing authority lives before you build

The tokenization engine signs administrative operations and never pays gas; the transaction engine pays gas and holds no authority. That split is the security model, and how it maps onto your custody arrangement is the part of an integration worth designing rather than discovering.

Environments

The whole stack runs against a public test network with no licence, no account and no expiry, which is the environment to build and test against. A commercial licence is required only on a public main network, and the software says which side it is on from the moment it starts, in its logs and on /license.

Keep a testnet deployment for CI after you go live. It costs nothing and it is the only place you can safely rehearse an upgrade.

Beyond this point

Custody integration, production topology, key ceremony, capacity planning and chain-specific operational procedure depend on your controls and your counterparties. They are part of an implementation engagement rather than a public page — a generic version would be wrong in exactly the specifics that matter.

Start the conversation when you get there.