List economic

Returns, oldest first and paged, the payments the caller's org made or received in a year, with the ones a correction restates named and what either party disputes — for the org's admins.

GET /v1/event/economic

Event → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/event/economic`
Method	`GET`
Operation	`get_event_economic`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns, oldest first and paged, the payments the caller's org made or received in a year, with the ones a correction restates named and what either party disputes — for the org's admins.

Request

5 fields.

Field	In	Type	Required	Description
`year`	query	integer	yes	Year is the calendar year to read, UTC.
`counterparty`	query	string	—	Counterparty keeps only payments with this org on the other side.
`rail`	query	string	—	Rail keeps only payments that moved on this rail.
`cursor`	query	string	—	Cursor continues from the next of the page before; empty starts the year.
`limit`	query	integer	—	Limit is how many events to answer, default 100 and at most 1000.

Response

Status	Body	Meaning
`200`	event.Economics	ok
`default`	problem-details	refused

200 body — 28 fields.

Field	In	Type	Always	Description
`disputes`	body	event.EconomicDispute[]	—	Disputes are what either party has disputed about the events in Rows.
`disputes[].at`	body	integer (int64)	—	At is when the dispute was filed, unix seconds.
`disputes[].by`	body	string	—	By is the org that disputes it: one of the event's two parties.
`disputes[].event`	body	string	—	Event is the id of the event disputed.
`disputes[].reason`	body	string	—	Reason is what the party says is wrong.
`next`	body	string	—	Next continues the read; empty on the last page.
`rows`	body	event.EconomicEvent[]	—	Rows are the events.
`rows[].agent`	body	string	—	Agent is the principal that acted for the buyer, as IAM names it.
`rows[].at`	body	integer (int64)	—	At is when the payment was made, unix seconds, as the rail recorded it.
`rows[].buyer`	body	string	—	Buyer is the org that paid.
`rows[].category`	body	string	—	Category is what the payment was for — service, goods, transfer, refund or royalty — as the rail recorded the parties agreeing it.
`rows[].chain`	body	string	—	Chain is the CAIP-2 network an on-chain payment moved on.
`rows[].corrects`	body	string	—	Corrects is the id of the event this one restates, when it is a correction.
`rows[].currency`	body	string	—	Currency is what the amounts are in: an ISO 4217 code or an asset symbol.
`rows[].fee`	body	string	—	Fee is what the rail kept of Gross, an exact decimal in Currency.
`rows[].fmv`	body	string	—	FMV is Gross's fair market value in U.S. dollars when it was paid, an exact decimal.
`rows[].gross`	body	string	—	Gross is what the buyer paid, an exact decimal in Currency.
`rows[].id`	body	string	—	ID is the event's identity, derived from its rail and proof.
`rows[].jurisdictions`	body	string[]	—	Jurisdictions are the ISO 3166 codes the payment is subject to, when the rail knows them.
`rows[].parent`	body	string	—	Parent is the agent that spawned Agent, when one did.
`rows[].proof`	body	string	—	Proof is the rail's own reference for the payment: a settlement id, a chain transaction hash or a processor reference.
`rows[].rail`	body	string	—	Rail is how the money moved: x402, ledger, chain, ach, wire, card, network or other.
`rows[].seller`	body	string	—	Seller is the org that was paid.
`rows[].service`	body	string	—	Service is what was bought, in the rail's own words.
`rows[].tax`	body	string	—	Tax is the tax collected within Gross, an exact decimal in Currency.
`rows[].tx`	body	string	—	Tx is the on-chain transaction hash of an on-chain payment.
`rows[].v`	body	integer (int64)	—	V is the schema version the event was stated in.
`superseded`	body	string[]	—	Superseded are the ids in Rows that a correction restates.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, EventApi } from 'hanzoai';

const api = new EventApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getEventEconomic({ year: 'year' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import EventApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = EventApi(client).get_event_economic(year='year')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.EventAPI.GetEventEconomic(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, event_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = event_api::get_event_economic(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.EventApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new EventApi(client).getEventEconomic();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/event/economic?year=1 \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP declares no tool for event — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

Event API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page