Skip to main content
The Token App exposes a REST API for administering tokens (mint, burn), querying historical data (mints, burns, holdings), and inspecting service status and health. All secured endpoints require an HTTP Bearer token in the Authorization header: 
Authorization: Bearer <token>
The code examples below assume two environment variables: 
export BASE_URL="https://<your-token-app-host>"
export TOKEN="<your-bearer-token>"

​
Admin

Write operations against the ledger. Both endpoints accept an idempotent command_id — repeating the same command_id won’t submit twice.

​
POST /api/admin/mint

Mint new units of an instrument to a recipient party.
​
command_id
string
required
Client-supplied idempotency key for the ledger submit.
​
instrument_id
string
required
Instrument to mint.
​
party_id
string
required
Recipient party id.
​
amount
number | string
required
Amount to mint. Accepts a number or a decimal string.
curl -X POST "$BASE_URL/api/admin/mint" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command_id": "mint-2025-01-01-001",
    "instrument_id": "rCC",
    "party_id": "alice::122...",
    "amount": "100.0"
  }'

{
  "command_id": "mint-2025-01-01-001",
  "status": "submitted"
}

​
POST /api/admin/burn

Burn units of an instrument held by a party.
​
command_id
string
required
Client- or system-assigned id for the ledger submit.
​
instrument_id
string
required
Instrument to burn.
​
party_id
string
required
Party whose tokens will be burned (holder or subject).
​
amount
number | string
required
Amount to burn.
curl -X POST "$BASE_URL/api/admin/burn" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command_id": "burn-2025-01-01-001",
    "instrument_id": "rCC",
    "party_id": "alice::122...",
    "amount": "10.0"
  }'
200 OK
{
  "command_id": "burn-2025-01-01-001",
  "status": "submitted"
}

​
Data

Read-only queries against the confirmed history captured by the token monitor. All endpoints support pagination via limit and offset query parameters and optional filtering by party_id and instrument_id.

​
GET /data/admin/mints

List confirmed mint records.
​
party_id
string
Filter by recipient party id.
​
instrument_id
string
Filter by instrument id.
​
limit
integer
default:"100"
Page size. Range: 1–1000.
​
offset
integer
default:"0"
Pagination offset (≥0).
curl -G "$BASE_URL/data/admin/mints" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "instrument_id=rCC" \
  --data-urlencode "limit=100"
200 OK
[
  {
    "command_id": "mint-2025-01-01-001",
    "created_at": "2025-01-01T00:00:00Z",
    "party_id": "alice::122...",
    "instrument_id": "rCC",
    "update_id": "1220abc...",
    "amount": "100.0"
  }
]

​
GET /data/admin/burns

List confirmed burn records. Same query parameters as /data/admin/mints. 
curl -G "$BASE_URL/data/admin/burns" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "instrument_id=rCC" \
  --data-urlencode "limit=100"
200 OK
[
  {
    "command_id": "burn-2025-01-01-001",
    "created_at": "2025-01-01T00:00:00Z",
    "party_id": "alice::122...",
    "instrument_id": "rCC",
    "update_id": "1220def...",
    "amount": "10.0"
  }
]

​
GET /data/admin/holdings

Return a snapshot of on-ledger holdings from the latest monitor scan.
​
party_id
string
Filter by owner party id.
​
instrument_id
string
Filter by instrument id.
​
limit
integer
default:"100000"
Page size. Range: 1–100000.
​
offset
integer
default:"0"
Pagination offset (≥0).
curl -G "$BASE_URL/data/admin/holdings" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "instrument_id=rCC"
200 OK
{
  "scan": {
    "scanned_at": "2025-01-01T00:00:00Z"
  },
  "total": 1,
  "holdings": [
    {
      "holding_cid": "0042...",
      "party_id": "alice::122...",
      "instrument_id": "rCC",
      "amount": "90.0",
      "locked": false
    }
  ]
}
The locked flag is true when a non-expired lock blocks spending (for example, an in-flight transfer).

​
Status

​
GET /status

Return the latest cached snapshot from the token-monitor loop (no live ledger query). Includes per-token stats (supply, holders, concentration, module-specific fields) and monitor/queue operational stats. Each section carries the time it was last refreshed; updated_at is the overall freshness. Fields that don’t apply to a token — or aren’t available yet — are omitted. The snapshot is only populated while monitoring is enabled; otherwise tokens is empty. 
curl "$BASE_URL/status" \
  -H "Authorization: Bearer $TOKEN"
200 OK
{
  "updated_at": "2025-01-01T00:00:00Z",
  "tokens": {
    "rCC": {
      "total_supply": "1000.0",
      "total_locked_supply": "10.0",
      "unique_holders": 42,
      "top_holder_share": "0.18",
      "supply_concentration_hhi": "0.07",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  },
  "operational": {
    "updated_at": "2025-01-01T00:00:00Z",
    "monitor": {
      "last_success_at": "2025-01-01T00:00:00Z",
      "age_seconds": 2.1,
      "last_scan_duration_seconds": 0.4,
      "poll_interval_seconds": 5,
      "last_scan_holdings": 42,
      "cycles_total": 12345,
      "cycle_errors_total": 0,
      "monitoring_enabled": true
    },
    "subscriptions": [
      {
        "name": "self-redeem",
        "queue_depth": 0,
        "queue_maxsize": 1024,
        "dropped_batches_total": 0
      }
    ],
    "modules": {}
  }
}
Key per-token fields:
FieldDescription
total_supplyTotal amount in circulation across all active holdings (spendable + locked), summed from the latest on-ledger scan.
total_locked_supplyPortion of total_supply currently locked (e.g. in-flight transfer) and not spendable.
unique_holdersNumber of distinct owner parties holding at least one active holding.
top_holder_shareFraction of total_supply held by the single largest holder (0–1).
supply_concentration_hhiHerfindahl–Hirschman Index of supply across holders. 1.0 = one holder owns everything; ~1/unique_holders = evenly distributed.

​
Health and metrics

Unauthenticated operational endpoints for orchestration and monitoring.

​
GET /healthz

Liveness probe. Returns 200 OK when the service is up.
cURL
curl "$BASE_URL/healthz"

​
GET /metrics

Returns service metrics in JSON.
cURL
curl "$BASE_URL/metrics"

​
Error responses

Validation errors are returned as 422 Unprocessable Entity: 
{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "value is not a valid number",
      "type": "value_error"
    }
  ]
}