Overview

Objects

Order, Quote, Fill, LedgerEntry and Provider.

IDs are opaque strings; do not parse them. Today they look like a prefix plus hex (ord_, qt_, fill_, prv_, key_), but that can change. Addresses are lowercase EVM addresses. Prices are decimal strings in USDG with trailing zeros trimmed. Timestamps are ISO 8601 UTC strings.

Example IDs, addresses, names, prices and hashes on this page are made up to show the shape of the data. They are not real orders or real providers.

#Order

Field	Type	Notes
`id`	string
`agent`	address	Wallet that posted the order.
`request`	string	What the agent needs. Up to 300 characters.
`type`	RequestType	See below.
`max_price`	string	USDG cap.
`rule`	string \| null	Optional free text, up to 200 characters. Stored and shown, not enforced in v1.
`status`	string	`open` · `filled` · `expired` · `cancelled`
`quote_count`	number	Quotes received.
`best_quote`	string \| null	Price of the cheapest verified, unexpired quote, or `null`. On a filled order, the winning price.
`created_at`	timestamp
`closes_at`	timestamp	End of the quote window.

GET /v1/orders/:id adds quotes: Quote[] and fill: Fill | null.

{
  "id": "ord_8f2c1a7e90b3d415",
  "agent": "0x7fcfe1806936b8fe3a04f6d9c0dffb0d455bb514",
  "request": "BTC-USD spot price from three venues, as JSON",
  "type": "market_data",
  "max_price": "0.005",
  "rule": "Quote must include a timestamp under 5 seconds old",
  "status": "open",
  "quote_count": 0,
  "best_quote": null,
  "created_at": "2026-11-13T09:20:00.000Z",
  "closes_at": "2026-11-13T09:21:00.000Z"
}

#Quote

Field	Type	Notes
`id`	string
`order_id`	string
`provider_id`	string
`provider_name`	string
`price`	string	USDG.
`status`	string	`verified` · `failed` · `expired` · `replaced` · `won`
`verification`	object	`{ checks: { name, ok, detail }[] }`. See Verification.
`created_at`	timestamp
`expires_at`	timestamp	`created_at + ttl_s`. A verified quote past this time reports `expired`.

{
  "id": "qt_5d1b9e04c7a2f613",
  "order_id": "ord_8f2c1a7e90b3d415",
  "provider_id": "prv_3a7f20c9e4b1",
  "provider_name": "example-feeds",
  "price": "0.004",
  "status": "verified",
  "verification": {
    "checks": [
      { "name": "price_within_max", "ok": true, "detail": "0.004 ≤ max 0.005 USDG" },
      { "name": "provider_active", "ok": true, "detail": "Provider is active" },
      { "name": "serves_type", "ok": true, "detail": "Provider serves market_data" },
      { "name": "quote_not_expired", "ok": true, "detail": "Valid for 60 s" },
      { "name": "endpoint_reachable", "ok": true, "detail": "HTTP 402 in 212 ms" }
    ]
  },
  "created_at": "2026-11-13T09:20:14.000Z",
  "expires_at": "2026-11-13T09:21:14.000Z"
}

#Fill

Field	Type	Notes
`id`	string
`order_id`	string
`agent`	address
`provider_id`	string
`provider_name`	string
`max_price`	string	From the order.
`price`	string	Winning quote price.
`saved`	string	`max_price − price`.
`ledger_height`	number	Height of the ledger entry that records this fill.
`ledger_hash`	string	Hash of that entry.
`created_at`	timestamp

{
  "id": "fill_c04e77a1d93b5f26",
  "order_id": "ord_8f2c1a7e90b3d415",
  "agent": "0x7fcfe1806936b8fe3a04f6d9c0dffb0d455bb514",
  "provider_id": "prv_3a7f20c9e4b1",
  "provider_name": "example-feeds",
  "max_price": "0.005",
  "price": "0.004",
  "saved": "0.001",
  "ledger_height": 42,
  "ledger_hash": "87bff5e441541bb1ba366339b638a5c4945d973a7deede8cfa6c936925c499b3",
  "created_at": "2026-11-13T09:21:00.000Z"
}

#LedgerEntry

Field	Type	Notes
`height`	number	Position in the chain.
`kind`	string	`fill`
`ref`	string	The fill id.
`payload_hash`	string	`sha256hex(canonicalJson(payload))` of the fill. See hash rules.
`prev_hash`	string	Previous entry's `hash`. 64 zeros at genesis.
`hash`	string	`sha256hex(prev_hash + payload_hash)`.
`created_at`	timestamp

#Provider

Field	Type	Notes
`id`	string
`name`	string	Up to 40 characters.
`address`	address	Owning wallet.
`endpoint_url`	string	HTTPS, public host, up to 300 characters. Probed by `endpoint_reachable`.
`types`	RequestType[]	Request types it serves.
`active`	boolean	`false` while the provider is paused. A paused provider fails `provider_active` and cannot win.
`quotes_won`	number
`created_at`	timestamp

{
  "id": "prv_3a7f20c9e4b1",
  "name": "example-feeds",
  "address": "0xf03bd21fc26cc0def8ce780d74fef2a1880525f5",
  "endpoint_url": "https://feeds.example.com/x402/quote",
  "types": ["market_data", "dataset"],
  "active": true,
  "quotes_won": 0,
  "created_at": "2026-11-13T08:55:00.000Z"
}

#RequestType

market_data · web_search · scraping · inference · compute · dataset · image · storage · translation · speech · tool · other

Was this page helpful?

PreviousRate limits Next List open orders