API reference

The Mints API is a REST/JSON API served from https://api.mints.sh. All requests require HTTPS. All responses are UTF-8 JSON.

Early access. Full per-endpoint reference — request schemas, every field, and error codes — publishes alongside GA and early-access developer credentials. The structure documented here is stable; individual fields may evolve before GA.

Gateway and namespaces

The gateway routes to three namespaces by path prefix:

Each namespace is versioned independently. The current version of all three namespaces is v1.

Authentication

Mints uses Keystone bearer sessions — centrally managed, short-lived tokens issued when a principal (human or agent) completes authentication. Every API request must include the session token in the Authorization header:

Authorization: Bearer msk_live_…

Tokens are scoped to the authenticated principal's lineage and the permissions granted during issuance. An agent's token can only operate on accounts that belong to its identity lineage. Cross-lineage requests are rejected with 403 Forbidden.

Early-access credentials arrive as part of your onboarding bundle and are scoped to the sandbox lane (api.mints.sh/sandbox/…). Production credentials are issued separately.

Response envelope

Every response wraps its payload in a standard envelope:

{
  "ok": true,
  "data": { … },
  "error": null,
  "meta": null
}

On error, ok is false, data is null, and error is an object:

{
  "ok": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Account balance is 8.20 USDC; transfer requires 12.50 USDC.",
    "request_id": "req_01JXG9…"
  },
  "meta": null
}

Paginated list endpoints include a meta object:

{
  "ok": true,
  "data": [ … ],
  "error": null,
  "meta": { "total": 84, "page": 1, "limit": 20 }
}

Example: check a balance

GET /banking/v1/accounts/me
Authorization: Bearer msk_live_…

{
  "ok": true,
  "data": {
    "did": "did:oas:l1fe:agent:7f3a…c9e2",
    "balance": "1250.00",
    "currency": "USDC",
    "custody": "self",
    "policy": {
      "daily_limit": "2500.00",
      "approval_threshold": "1000.00"
    }
  },
  "error": null,
  "meta": null
}

Example: send a payment

POST /banking/v1/payments
Authorization: Bearer msk_live_…
Content-Type: application/json

{
  "to": "did:oas:l1fe:agent:9b1d…44f0",
  "amount": "12.50",
  "currency": "USDC",
  "memo": "inference compute — batch 48"
}

{
  "ok": true,
  "data": {
    "tx": "tx_01JXF8…",
    "status": "settled",
    "amount": "12.50",
    "currency": "USDC",
    "latency_ms": 142,
    "settled_at": "2026-06-13T18:04:22Z",
    "receipt_url": "https://api.mints.sh/banking/v1/payments/tx_01JXF8…/receipt"
  },
  "error": null,
  "meta": null
}

Example: resolve an identity

GET /identity/v1/resolve?did=did:oas:l1fe:agent:7f3a…c9e2
Authorization: Bearer msk_live_…

{
  "ok": true,
  "data": {
    "did": "did:oas:l1fe:agent:7f3a…c9e2",
    "kind": "agent",
    "lineage": "rooted",
    "root": "did:oas:l1fe:hmr:…",
    "verified": true,
    "created_at": "2026-05-01T09:00:00Z"
  },
  "error": null,
  "meta": null
}

HTTP status codes

Idempotency

POST endpoints that create or mutate resources accept an optional Idempotency-Key header. Use a UUID or similarly unique value generated client-side. The same key replayed within 24 hours returns the original response without re-executing the operation.

Idempotency-Key: 018f3c2d-7b4a-7e1c-9d2f-3a5b6c8d0e1f

Next steps

• Quickstart — CLI-first intro to your first settled payment
• x402 payments — HTTP-native payment flow in depth
• Early access — request API credentials