The API playbook

A better response starts with a better question.

Inspect, copy, and download fictional JSON patterns for asset identity, balances, events, and useful errors.

Reference patterns, not a live API. All records below are fictional, local examples. No request is sent and no account or wallet is connected. Downloadable JSON files contain exactly the example shown.

Asset identity

Keep the network and asset reference separate from a display symbol. This fictional record uses an illustrative namespace, not a deployable address.

{
  "example": true,
  "schema_version": "reference-1",
  "asset_id": "demo:membership/sample",
  "network_id": "demo:reference-network",
  "symbol": "SAMPLE",
  "name": "Fictional Membership Credit",
  "decimals": 6,
  "metadata_source": "fictional-fixture"
}

Download JSON ↓

Balance observation

A raw amount is not a fiat valuation. Preserve scale, observation context, and partial coverage instead of converting missing information into zero.

{
  "example": true,
  "asset_id": "demo:membership/sample",
  "account_id": "demo:account-01",
  "amount_raw": "1250000",
  "decimals": 6,
  "display_amount": "1.25",
  "observed_at": "2026-09-01T12:00:00Z",
  "coverage": {
    "state": "partial",
    "reason": "Second example account unavailable"
  },
  "valuation": {
    "state": "unavailable",
    "amount": null
  }
}

Download JSON ↓

Event envelope

Distinguish the logical event from a delivery attempt. These names illustrate an application design; they are not a provider-specific delivery or signing contract.

{
  "example": true,
  "event_id": "demo:event-1042",
  "delivery_id": "demo:delivery-02",
  "event_type": "balance.observed",
  "schema_version": "reference-1",
  "occurred_at": "2026-09-01T12:00:00Z",
  "received_at": "2026-09-01T12:00:03Z",
  "resource": {
    "asset_id": "demo:membership/sample",
    "account_id": "demo:account-01"
  },
  "processing_state": "accepted"
}

Download JSON ↓

An honest error

An unavailable source should return an explicit failure state. This fixture describes a retryable dependency issue without exposing internal credentials or private account data.

{
  "example": true,
  "request_id": "demo:request-080",
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "message": "The example source could not be reached.",
    "retryable": true,
    "retry_after_seconds": 30
  },
  "data": null,
  "coverage": {
    "state": "unavailable"
  }
}

Download JSON ↓

Identity before labels

A symbol helps a person read a result. A stable network-aware identifier helps software join it without guessing.

Coverage before confidence

A fresh fetch can contain stale or partial observations. Keep the reason visible alongside the result.

Evidence before conclusions

An accepted event is not proof of a completed business action. Document the next state and its evidence.

Adapt the contract, not just the field names

Choose the network, provider, and resource types your application actually needs. Verify the upstream semantics before mapping them into a local model. These examples deliberately avoid real addresses, endpoint credentials, and claims of network compatibility. The demo: namespace belongs only to these fictional fixtures.

For production, define authorization, exact arithmetic, schema validation, stable pagination, bounded retries, monitoring, and a recovery path. The simplified fixtures omit those mechanisms because they are reference data, not a complete server implementation. Never place a privileged API key in a public browser bundle.

Follow a worked explanation

The API architecture guide expands the observation model. The webhook guide explains how receipt, durable processing, and replay fit together. Review the API security guide and the data-quality checklist before extending a prototype.