Designing for Composability

Most blockchain APIs are single-purpose. Verify a token holding. Check NFT ownership. Confirm a transaction. Each call returns a result and the integration ends there. We built InsumerAPI around a different assumption: verification is rarely the final step. It is the beginning of a flow that crosses the boundaries between verification, compliance, and commerce.

Atomic APIs and the wiring problem

Blockchain verification APIs tend to be isolated. You call an endpoint, get a result, and move on. But the use cases that matter are rarely that simple.

A merchant wants to verify a customer's token holdings, check their discount eligibility, issue a signed code, and confirm an on-chain payment. A compliance officer wants to run a KYC check, generate a provable attestation, and store it as an audit artifact. An AI agent wants to browse a merchant directory, evaluate discounts across multiple storefronts, and execute a purchase.

Each of these requires multiple API calls that feed into each other. If the API does not model those connections, every integrator builds the wiring from scratch. The burden shifts from the system designer to the developer. We decided that was the wrong default.

Typed inputs, typed outputs

Each of the 26 endpoints in InsumerAPI exposes typed ports. Named inputs and outputs. When the output type of one endpoint matches the input type of another, they compose directly.

POST /v1/attest produces a signature and a kid (key identifier). GET /v1/jwks accepts that kid and returns the corresponding public key. Verification of an attestation's signature flows from one endpoint to the other through a shared type. No glue code required.

The type verificationCode is particularly important for gating access on wallet state. It is produced by three endpoints: POST /v1/verify, POST /v1/acp/discount, and POST /v1/ucp/discount. It is consumed by two: GET /v1/codes/{code} and POST /v1/payment/confirm. That single type is the point where verification crosses into commerce. Three different paths produce it. Two different paths consume it. The type is the contract.

The most connected type is merchantId, which flows through 15 of the 26 endpoints. It is the through-line for the entire commerce and onboarding pipeline. A wallet address connects to 8 endpoints across verification, commerce, and payment confirmation. These are not incidental overlaps. They reflect deliberate decisions about how the system should compose.

Two credit economies

This is the most deliberate design decision in the API.

Most APIs have one billing layer. InsumerAPI has two. API credits and merchant credits operate independently, serve different actors, and are consumed at different points in a flow.

API credits are consumed by developers building verification logic. Creating an attestation costs 1 credit. Generating a trust profile costs 3. A Merkle-proved attestation costs 2. These are the costs of verification.

Merchant credits are consumed by businesses issuing discount codes. Generating a signed verification code costs 1 merchant credit, whether through the standard verify endpoint, the ACP format, or the UCP format. This is the cost of issuing commercial value.

The separation exists because the actors are different. A developer building an AI agent should not bear the cost of a merchant's discount issuance. A merchant configuring their storefront should not pay for a developer's compliance checks. The credit systems are segmented because the economic relationships are segmented.

This also creates a deliberate free layer. A developer can explore the entire merchant directory, check any wallet's discount eligibility, validate any existing code, and browse the token registry. All at zero cost. The privacy guarantees apply identically across both credit economies. The system charges only when new signed artifacts are created: attestations (developer cost) and verification codes (merchant cost). An agent can evaluate the full landscape before committing a single credit.

Three compositions

The system defines 17 reference patterns. Rather than enumerate all of them, five compositions illustrate what typed composability looks like in practice.

Zero-cost discovery loop. An agent calls GET /v1/merchants to browse the directory, optionally filtering by token symbol. It picks a merchant and calls GET /v1/merchants/{id} for full details: accepted tokens, NFT collections, discount tiers. Then it calls GET /v1/discount/check with a wallet address to preview what discount that wallet qualifies for. Three calls. Zero credits. The agent now has complete information to decide whether to proceed to a paid discount code.

KYC-gated agent commerce. An agent calls GET /v1/compliance/templates to discover available compliance checks. It feeds the template name into POST /v1/attest as a condition. If the wallet passes the compliance check, the agent proceeds to POST /v1/acp/discount to generate an ACP-format coupon with per-item allocations. Compliance and commerce composed in one chain. Cost: 1 API credit for the attestation, 1 merchant credit for the discount.

Trust-informed discount. An agent calls POST /v1/trust to generate a trust profile for a wallet, scoring it across multiple dimensions: transaction history, token diversity, NFT activity, DeFi participation. If the wallet shows legitimate on-chain activity rather than airdrop farming, the agent proceeds to check discount eligibility and generate a signed code. Anti-fraud logic and commerce composed in a single flow. Cost: 3 API credits for the trust profile, 1 merchant credit for the code.

Trust-gated regulated commerce. An agent calls POST /v1/trust to screen a wallet across multiple dimensions. If the wallet passes the trust threshold, the agent proceeds to a compliance attestation using POST /v1/attest with a compliance template condition. If the wallet passes compliance, the agent generates an ACP discount via POST /v1/acp/discount. Three layers of gating — trust, compliance, commerce — composed in a single flow. This is the pattern for regulated or high-value commerce where both counterparty trust and regulatory eligibility matter before issuing a discount.

Agent trust handshake. Before delegating a task or accepting a transaction, an agent calls POST /v1/trust on the counterparty's wallet. The returned trust profile scores the wallet across 4–6 dimensions. The agent verifies the ECDSA signature via GET /v1/jwks to confirm the profile is authentic and unmodified. Based on the trust dimensions, the agent decides whether to proceed. This pattern is already live in production — DJD Agent Score uses it to evaluate wallet trust before agent interactions.

Each of these compositions crosses category boundaries. Verification feeds compliance. Compliance feeds commerce. Trust informs pricing. Trust gates delegation. The API was designed so these boundaries are permeable, not walls.

Making the structure explicit

The composability described above could remain implicit, buried across documentation pages. We chose to make it explicit.

The API's typed ports and connections are defined in a machine-readable schema. Each endpoint declares its inputs and outputs with named types. Each connection between endpoints is declared explicitly in the schema, not inferred from documentation. The schema defines 22 port types, 22 explicit connections, and 17 reference patterns covering commerce automation, compliance gating, risk scoring, institutional audit, regulated commerce, agent trust, and agent-driven onboarding.

The API Topology page visualizes this schema as an interactive graph. Endpoints are positioned by category. Connections are drawn between compatible ports. Reference patterns highlight the endpoints involved in each composition, with credit costs and data flows.

It is more than a visual diagram. It reflects the machine-readable schema that defines how endpoints compose. A developer can see exactly which outputs feed which inputs, which patterns are canonical, and what each composition costs.

InsumerAPI was designed to support multi-step flows that cross verification, compliance, commerce, and onboarding. The topology makes those flows visible. The schema makes them explicit.