API Reference on Sankofa Engine Documentation

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

The Sankofa Engine supports two authentication models. Most integrations use JWT bearer tokens for API access. Self-custody deployments additionally use ECDSA transaction signing to authorize individual transactions without sharing private keys.

For interactive exploration, see the API Explorer.

JWT Authentication (Default)

Sankofa Labs provisions API credentials (client_id and client_secret) during onboarding. Your application exchanges these credentials for a short-lived JWT token, then includes that token on every request.

1. Obtain a Token

POST /v1/auth/token

API Explorer (Swagger UI)

Mon, 01 Jan 0001 00:00:00 +0000

Transactions

Mon, 01 Jan 0001 00:00:00 +0000

The Transactions API lets you submit financial operations (debits, credits, transfers, exchanges, mints, and burns), check their processing status, and query transaction history. All transactions are processed asynchronously and are immutable once completed.

For interactive exploration, see the API Explorer.

Important

All monetary amounts are represented as strings, not numbers. This avoids IEEE 754 floating-point precision issues. For example, use "100.00" instead of 100.00. Amounts are limited to 18 integer digits and 18 decimal digits.

Request Limits

All POST requests must include the Content-Type: application/json header. The maximum request body size is 1 MB.

Transaction Types

Type	Description	Example Use Case
`credit`	Funds in — increases account balance	Cash deposit, incoming wire
`debit`	Funds out — decreases account balance	Withdrawal, fee deduction
`transfer`	Move between accounts (pair with `group_id`)	Internal account-to-account transfer
`exchange`	Asset swap between token types	Currency conversion
`mint`	Create new token supply	Token issuance
`burn`	Destroy token supply	Token redemption

Single-Leg vs. Multi-Leg Transactions

Single-leg transactions operate on one account with no counterpart — a cash deposit (credit) or withdrawal (debit) where funds enter or leave the system.

Accounts

Mon, 01 Jan 0001 00:00:00 +0000

The Accounts API provides read-only access to account state, token balances, and NFT ownership. These endpoints are served from a PostgreSQL projection layer, which means they are fast but eventually consistent with the underlying ledger.

Account ID Format

Account identifiers must be ASCII-only, at most 128 characters, and may only contain: a-zA-Z0-9_.-:. Requests with invalid account IDs are rejected with a 400 Bad Request error.

For interactive exploration, see the API Explorer.

Tokens & NFTs

Mon, 01 Jan 0001 00:00:00 +0000

The Tokens API covers registration and querying of both fungible tokens and non-fungible tokens (NFTs). Fungible tokens represent interchangeable assets (currencies, loyalty points, carbon credits). NFTs represent unique items with individual provenance tracking.

For interactive exploration, see the API Explorer.

Important

All numeric values representing quantities or supplies are encoded as strings to avoid IEEE 754 floating-point precision issues. The decimals field (0-18) defines the token’s precision.

Fungible Tokens

Register a Token

POST /v1/fungible-tokens

Compliance & Attestations

Mon, 01 Jan 0001 00:00:00 +0000

The Compliance API enables privacy-preserving audits and verifiable attestations. Using zero-knowledge proofs (ZKPs), the Sankofa Engine can generate cryptographic assertions that prove specific facts about the ledger – such as solvency or asset provenance – without revealing the underlying data. This allows regulated entities to demonstrate compliance to auditors and regulators while preserving the confidentiality of individual account balances and transaction details.

For interactive exploration, see the API Explorer.

Zero-Knowledge Proof Assertions

The assertions API generates ZKP proofs that can be independently verified. Each proof is a cryptographic object that demonstrates a specific claim is true, without disclosing any of the private inputs used to construct it.