HTTP API design

The HTTP interface is defined in specs/openapi.draft.json. It is a protocol contract, not a live endpoint. Released interfaces are listed in implementation status.

Request principles

Require a profile/version, operation identifier, explicit expected context, and bounded evidence references. Do not execute arbitrary user-supplied code or policies. Financial values use integer strings, with a network and exact asset identity. URLs are untrusted inputs subject to fetch policy.

The idempotency key binds the caller and request digest. Reusing a key with different inputs fails. Each released endpoint specifies its authentication, payment, and permission requirements.

Responses

Processing state, artifact validity, evaluation, and local acceptance remain separate fields. A completed evaluation with FAIL is not a server error. Missing evidence yields INDETERMINATE. Structured error codes carry an explanation and machine-readable requirements.

Keep asynchronous timestamps and future-source selections as jobs. No synchronous endpoint may promise confirmed Bitcoin evidence before it exists.

OpenAPI limitations

The draft schema documents interface structure, not cryptographic validity. It does not certify finality, signature algorithms, refund behavior, or production authorization. The error catalogue and signing/canonicalization profile require tests before implementation is declared compatible.

<!-- p21-source-payment-v08 -->

Payment evidence and exactly-once accounting

An invoice binds caller, request digest, idempotency key, exact network and asset identity, merchant recipient, integer atomic amount, service-credit entitlement, expiry and settlement policy. A payment adapter checks an executed transfer event and its destination, amount, deployment identity, canonical block, confirmations, index coverage and supported rule revision. A transaction ID, mempool observation, inscription creation or wallet balance screenshot is not payment settlement.

Store event uniqueness using network, asset deployment, transaction and operation/inscription identity. Bind invoice ownership to the caller through the invoice contract rather than accepting any submitted transaction hash. Use atomic ledger transactions and unique constraints for settlement crediting, job reservation, consumption and release. Network retries and webhook replay never create another credit or charge. Missing evidence, lagging/conflicting indexers and reorganizations remain pending or require review. Define a compensating journal and operator-loss policy for a deep reorganization; do not silently debit another customer payment.

Commercial activation and implementation status

NAT and USDC are both required for the initial commercial-launch acceptance test. Public documentation, source code and policy fixtures are not live payment endpoints. The static payment-policy resource lists required launch methods with enabled: false, no recipient and no live endpoint until each rail passes end-to-end settlement, accounting, failure/reorganization, security and owner-approval gates. Do not advertise a USDC-only release as the completed initial payment scope.

No token has been issued, no source element is announced, and no mainnet inscription, customer charge, treasury swap or wallet authorization is performed by this release. Production service availability remains separate from website publication. No Trac partnership, hosted SLA or independent cryptographic audit is implied.

[1] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/digital-elements/.element-registry

[2] https://github.com/Trac-Systems/ord-tap/blob/b8f6ea35cf6b9d405d4db7c58555e3c8ab33e8cd/src/index/updater/inscription_updater/tap/ops/dmt_element.rs

[3] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/nat-use-cases/usdnat-method-1-live

[4] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/non-arbitrary-tokens-nats/nat-token-transfer

[5] https://docs.x402.org/core-concepts/network-and-token-support

[6] https://github.com/Trac-Systems/ord-tap/blob/b8f6ea35cf6b9d405d4db7c58555e3c8ab33e8cd/README.md

[7] https://arxiv.org/abs/1605.04559

<!-- p21-enforcement-v10 -->

Authorization schemas are not live endpoints

The repository publishes draft JSON Schemas for p21.authorization.v1, p21.consumer-decision.v1 and p21.equivocation-evidence.v1. They are versioned wire-format candidates for interoperability and conformance tests. The current OpenAPI document does not expose production authorization, signing, decision or dispute routes, and no client should infer such authority from schema availability.