Reference Token Minting API Resources & Errors

Endpoint map

Small surface, explicit resources.

POST /v1/mints

Create or replay one idempotent mint operation. Returns 202 with the durable resource.

GET /v1/mints/{id}

Retrieve current operation state, immutable intent, errors, and chain evidence.

POST /v1/mint-batches

Create a parent resource with normalized child items and explicit transaction grouping.

GET /v1/assets/{id}

Read approved asset identity, capabilities, network, standard, and public policy metadata.

GET /v1/events/{id}

Retrieve a webhook event for audit and controlled redelivery workflows.

POST /v1/webhook-endpoints

Administrative control-plane operation; secure separately from routine mint submission.

Object: asset

Reviewed configuration, not caller-supplied chain code.

Field	Type	Meaning
`id`	string	Stable application identifier used in mint requests.
`network`	string	Approved chain or cluster identifier.
`standard`	enum	`erc20`, `spl`, `erc721`, or `erc1155`.
`chain_reference`	object	Contract, mint, program, collection, token ID policy, or other network identity.
`decimals`	integer\|null	Display conversion for fungible amounts.
`capabilities`	array	Mint amount, unique item, batch, metadata, burn, freeze, or other supported operations.
`status`	enum	Disabled, test-only, enabled, paused, or retired.

Create operation

Require idempotency and a server-side asset ID.

Do not accept arbitrary contract addresses, ABIs, method selectors, or program IDs on the public mint endpoint.

Authenticate before key lookup.
Bind the key to tenant and canonical payload.
Reject a changed payload under the same key.
Create the operation before external side effects.

POST /v1/mints
Idempotency-Key: 5db1d9ee-8f64-4b33-9b0b-62a8d4f7f9e0
Content-Type: application/json

{
  "asset_id": "loyalty-token-v2",
  "recipient": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
  "amount": "250.50",
  "amount_unit": "display",
  "external_reference": "reward_84721",
  "metadata_version_id": null
}

Reference create request. Replace example values and apply your own authentication, authorization, and signing policy.

{
  "id": "mnt_01J8D4W7Q2",
  "object": "mint_operation",
  "status": "confirmed",
  "asset_id": "loyalty-token-v2",
  "network": "ethereum-sepolia",
  "standard": "erc20",
  "recipient": "0x8ba1...BA72",
  "amount": {
    "display": "250.50",
    "base_units": "250500000",
    "decimals": 6
  },
  "chain_details": {
    "transaction_hash": "0x92f4...a81c",
    "block_number": "7219042",
    "confirmations": 12
  },
  "created_at": "2026-10-23T19:42:18Z",
  "confirmed_at": "2026-10-23T19:43:02Z"
}

Reference confirmed operation. Replace example values and apply your own authentication, authorization, and signing policy.

Object: mint_operation

Preserve intent and evidence together.

Immutable asset, recipient, amount or item data
Status and stable error code
Idempotency and external-reference correlation
Transaction lineage and confirmation context
Chain-specific fields in chain_details
Created, submitted, confirmed, and reconciled timestamps

Error model

Tell clients whether to correct, wait, or escalate.

Code	HTTP or operation context	Retry guidance
`invalid_request`	4xx response before operation creation	Correct fields; a new idempotency key may be used for new intent.
`idempotency_key_reused`	409 response	Use the existing request or a new key for genuinely different intent.
`asset_not_allowed`	4xx policy denial	Do not retry unchanged; update authorization or asset state.
`signer_denied`	Operation failure	Inspect policy and configuration; no blind retry.
`rpc_unavailable`	Transient operation state	Server retries; client reads the existing operation.
`chain_execution_failed`	Operation failure with transaction evidence	Correct the underlying cause before a new business request.
`submission_unresolved`	`needs_review`	Do not issue again until reconciliation proves the outcome.
`reconciliation_mismatch`	`needs_review`	Escalate with chain evidence; automatic remint blocked.

Signed delivery

Webhooks are at-least-once events.

Receivers verify a signature and timestamp, deduplicate by event ID, and retrieve the operation when they need the complete current representation.

Stable event ID across delivery retries
Timestamped signature over raw payload bytes
Per-endpoint secret rotation
Bounded exponential backoff
Delivery logs without secret exposure

{
  "id": "evt_01J8D52AVB",
  "type": "mint.confirmed",
  "created_at": "2026-10-23T19:43:02Z",
  "data": {
    "object": {
      "id": "mnt_01J8D4W7Q2",
      "status": "confirmed",
      "asset_id": "loyalty-token-v2",
      "transaction_id": "0x92f4...a81c"
    }
  }
}

Reference webhook event. Replace example values and apply your own authentication, authorization, and signing policy.

Build from explicit contracts

Use the reference architecture as a starting point.

Define assets, authorities, idempotency, confirmation, and reconciliation before connecting a production signer.

Open documentation Contact MintAPI.com