Hirakumi Ties Cardano API Payments to Response Checks

Hirakumi lets AI agents retain purchased credits when a data service returns stale information, missing fields, or a failed request. Developed for TOKEN2049, the prototype connects existing APIs with x402 payments and the Masumi agent registry. It currently operates on Cardano Preprod using test USDM tokens.

A Price Request Shows How API Credits Work

The public Live Crypto Prices example demonstrates the billing rules. An agent requests a cryptocurrency price, and the API must return the required fields with a timestamp no more than 15 minutes old.

An hour-old reading fails the check and consumes no credit. Failed requests and responses missing required fields receive the same treatment. When a response meets the conditions, the agent receives it and the pack balance falls by one credit.

The displayed offer prices 100 calls at 2 tUSDM. One payment on Cardano funds the pack, after which individual requests pass through Hirakumi’s gateway without a separate blockchain transaction for each response.

A JSON Schema rule defines the required fields, data types, and permitted age of the information. The gateway checks responses against those conditions before deducting credits. These checks establish format and freshness; they do not independently confirm that a reported market price is accurate.

Existing APIs Connect to Masumi Agents

According to the project’s documentation, providers can list an API without changing its code. They supply its address and sample requests, verify domain ownership through a DNS record, and sign to connect a payout address. Hirakumi runs test calls and prepares the service description.

The provider approves the price and response conditions before publication. A cryptographic hash records those conditions before any sale, and the service is registered on Masumi for discovery by agents.

When an agent requests paid access, x402 returns an HTTP 402 response containing the offer. The agent pays for a pack and uses its credits through Hirakumi’s gateway, which calls the underlying API and validates the results. Any required provider API key remains with the gateway.

The roles are distinct: Masumi supplies registration and discovery, x402 connects web requests with payment, and Hirakumi checks the delivered responses. Providers can also begin setup by assigning a task to the Hirakumi agent on Sokosumi.

Cardano Escrow Settles Accepted Usage

Hirakumi supports direct payment and escrow. Direct payments go immediately to the provider while the gateway tracks credits. Escrow locks funds in a Cardano smart contract written in Aiken.

The escrow option is intended for larger packs, new providers, services with weaker availability, or buyers who request it. In this model, the buyer’s agent also checks responses and signs receipts for those it accepts.

Settlement uses those receipts to calculate the final distribution, with an opportunity to submit a newer receipt before the pack closes. According to the project, the provider receives payment for accepted responses, Hirakumi collects a 3% fee, and the remaining funds return to the buyer.

The public site links to test transactions for registration and settlement. Its status page distinguishes automated availability checks from paid activity and records service interruptions.

The browser demo brings those components together: visitors can request a price through the gateway, inspect the response and receipt, and see the remaining credits in the test pack. The interface also provides the service’s Masumi registry identifier and payment transaction for inspection.