Server definition
- Hash
- sha256:0a460c1b225ec77b1fbe908e8699f997ae5fe1c06e09b261d1952399a21e6eb2
- What it is
- What a remote MCP server returned when asked what it offers: 40 tools
The blob, as servednamed by its sha256
{
"instructions": "GreenlandAI — the command centre for the machine economy: ONE keyless MCP endpoint over the live GreenlandAI / JoulePAI / RAREEAI / ENYAL surface (the world graph — companies, resource deposits, infrastructure, projects and commodities, with the relationships between them — and the map; the RAREEAI marketplace + oracle network; wallets; on-chain verification). ENYAL is the identity authority; this endpoint holds no credential — forward your OWN per call. An ENYAL OAuth access token (`eyl_` followed by a JWT, sent as Bearer) works across ALL products; an API key is product-specific (an ENYAL `eyl_` API key is an ENYAL key, a JoulePAI key does not reach the graph, a GreenlandAI key does not reach wallet/marketplace). Send it as Authorization (Bearer `eyl_...`) or X-API-Key; the backend applies auth, scope, ownership and metering. Reads are metered against the CALLING agent's OWN wallet (not the owner's) — read it FREE with the `joules_balance` tool (a GreenlandAI agent key `gai_`/`gqa_` reads its own balance; a `jlp_`/`eyl_` credential reads by wallet_id). The debit is the base price plus a ~0.5% rail surcharge rounded up (a 100 J read debits 101 J); call the `billing_quote` tool for the exact all-in price of a path before you call it, and the `billing_attempts` tool afterwards for your own charge record (reserved vs settled per attempt — verify your bill yourself). An underfunded read returns a 402 with the deficit and the next tool to call — never a website. A GreenlandAI agent funds its OWN wallet with USDC on Base at its own address (GET /api/v1/agent/me/deposit-address with the agent key; `funding_prepare` gives it) or is funded by its OWNER (POST /api/v1/agents/{agent_id}/fund with the owner's session). Starting from no account: one email verification done by API (no browser), at least 5 USDC on Base, then unattended — the seven steps are in greenlandai.ai/llms.txt (Cold start). A read past the daily cap your OWNER set for you returns a 402 `owner_cap_reached` (or `owner_allowance_required`) instead: not a shortfall, funding does not lift it, nothing is charged; it clears at 00:00 UTC or when the owner acts. Metering RESERVES against your balance before the read and SETTLES after for what was delivered: an empty result settles to zero, a partial result settles for the part delivered, and a 4xx, 5xx or server exception RELEASES the reservation (that request produced nothing, so nothing is charged). But a read the backend has already answered SETTLES even if you disconnect or time out waiting for it — the work was done, so an abandoned or timed-out call after delivery is still charged. A genuine retry of the SAME request within 15 minutes (same credential + key + request) is served free from the first charge (cached); a different request is a new charge. Price with `billing_quote` first and check `billing_attempts` afterwards for what you were actually charged. Every metered JSON response carries a top-level `charged_joules` (the all-in PRICE) and a `metering` block written after the settle — `metering.settlement` (settled | settled_zero | settle_failed | released | unknown) is whether you PAID and `metering.settled_joules` what left your wallet; settle_failed = delivered but unpaid, and the wallet is locked until it clears. Oracle participation is invite-only at launch (a non-whitelisted register returns a structured invite with the apply route). A verify result is ENYAL's index answer, not itself an on-chain proof.",
"tools": [
{
"description": "Cryptographic inclusion proof for YOUR wallet balance in the latest hourly transparency\n attestation (GET /wallet/balance-proof): leaf hash, Merkle sibling path, root, the anchoring BSV\n txid, and `verification` (the steps to recompute the root and check it on chain). Bearer required;\n the wallet is the one your credential owns — there is NO wallet_id argument, the backend resolves it\n from your token. Anchoring is batched exactly like transparency_latest: `bsv_txid` may read \"pending\"\n until this attestation's OP_RETURN batch (five per transaction, roughly every five hours) is\n broadcast — not-yet-batched is not unanchored; for the most recent anchored root read\n transparency_latest.last_anchored.",
"inputSchema": {
"properties": {},
"title": "balance_proofArguments",
"type": "object"
},
"name": "balance_proof",
"outputSchema": {
"additionalProperties": true,
"title": "balance_proofDictOutput",
"type": "object"
}
},
{
"description": "YOUR OWN CHARGE RECORD — what this wallet was charged for, attempt by attempt, so you can verify your\n bill without asking us (relays GET /api/v1/billing/attempts; own wallet only — derived from your credential,\n never a parameter). Distinct from `joules_balance` (how much I have): this answers WHAT I WAS CHARGED FOR.\n Each item: `status` — pending = reserved, not yet settled · completed = settled; `settled_all_in_joules` left\n the wallet (base + the 0.5% rail fee) · settled_zero = delivered nothing, nothing moved · failed = released,\n nothing moved (a 4xx, a 5xx, a refused reservation) · settle_failed = delivered but unsettled — new queries\n refuse until it clears · expired = past the 15-minute replay window, superseded · refunded = reversed in full.\n `reserved_joules` vs `settled_joules` is the settle-for-delivered difference (partial hops, empty results).\n Match `attempt_id` to `metering.attempt_id` in the response body you got (or the `X-Metering-Attempt` header /\n `price.attempt_id`; `look_at`'s image result carries it as `metering_attempt`).\n `limit` 1-200 (default 50), `offset` for paging. Bearer or agent key required.",
"inputSchema": {
"properties": {
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Limit"
},
"offset": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Offset"
}
},
"title": "billing_attemptsArguments",
"type": "object"
},
"name": "billing_attempts",
"outputSchema": {
"additionalProperties": true,
"description": "billing_attempts — the caller's own charge record (GET /api/v1/billing/attempts): items[] of\n{attempt_id, when, settled_at, endpoint, query_type, status, reserved_joules, settled_joules,\nsettled_all_in_joules, idempotency_key, transfer_id, detail} + count + wallet_id + a statuses legend.\nItems stay opaque (list[Any]) so a backend field this relay does not model passes through verbatim.",
"properties": {
"count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Count"
},
"items": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Items"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
},
"statuses": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Statuses"
},
"wallet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Wallet Id"
}
},
"title": "AttemptsOut",
"type": "object"
}
},
{
"description": "The exact per-caller price of a metered call BEFORE you make it — free, no website, an MCP tool you\n can actually invoke (relays GET /api/v1/billing/quote). `path` = the API path the call would hit — e.g.\n \"/api/v1/relationships\" (the `relationships` tool), \"/api/v1/look.from\" (`look_from`), \"/api/v1/map.viewport\"\n (`map_viewport`), \"/api/v1/companies/{id}\" (`company`), \"/api/v1/deposits\" (`deposits`),\n \"/api/v1/deposits/{id}\" (`deposit`), \"/api/v1/nearby\" (`nearby`); `hops` = graph depth for a relationships path\n (an agent key goes to 10 hops — every agent is on one set of terms; a human session to 3). Priced for YOU. Read\n `joules_all_in` — the TRUE debit (base `joules` + `rail_fee_joules`, the 0.5% rail surcharge); fund\n that, not the base. Graph paths price per hop and refund unused/empty hops\n (`refund_on_empty`/`quote_is_maximum`). Bearer required, but NO verification — an unverified caller may\n still price a call.",
"inputSchema": {
"properties": {
"hops": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Hops"
},
"path": {
"title": "Path",
"type": "string"
}
},
"required": [
"path"
],
"title": "billing_quoteArguments",
"type": "object"
},
"name": "billing_quote",
"outputSchema": {
"additionalProperties": true,
"description": "billing_quote — covers BOTH backend shapes (pricing_model 'per_hop' carries billed_hops /\nrate_per_hop / refund_on_empty / quote_is_maximum; 'flat_query_type' omits them). All optional,\nso neither shape errors.",
"properties": {
"billed_hops": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Billed Hops"
},
"hops": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Hops"
},
"joules": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "BASE price, before the rail surcharge",
"title": "Joules"
},
"joules_all_in": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "THE TRUE DEBIT — fund this, not `joules`",
"title": "Joules All In"
},
"partial_refund_note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Partial Refund Note"
},
"path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Path"
},
"peg": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Peg"
},
"pricing_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pricing Model"
},
"pricing_tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pricing Tier"
},
"query_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query Type"
},
"quote_is_maximum": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Quote Is Maximum"
},
"rail_fee_joules": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "the ~0.5% rail surcharge, rounded up",
"title": "Rail Fee Joules"
},
"rate_per_hop": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Rate Per Hop"
},
"refund_on_empty": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Refund On Empty"
},
"usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Usd"
}
},
"title": "QuoteOut",
"type": "object"
}
},
{
"description": "Cryptographic inclusion proofs for YOUR Bridge Ledger rows — contribution/fee events — in the\n balance-proof shape (GET /programme/bridge/proof): per-row leaf hash, sibling path, the `bridge_root`,\n and the anchoring BSV txid, plus `verification`. Bearer required; scoped to the holder your token\n resolves to — no argument. `anchoring` is either \"anchored\" (with a real 64-hex `bsv_txid`) or a\n pending note: Bridge rows are anchored by being batched into the hourly transparency attestation\n (five attestations per OP_RETURN transaction, roughly every five hours), so the newest rows read\n pending until their batch is broadcast and then carry the batch txid. Nothing is computed on request\n — it reads what the attestation stored.",
"inputSchema": {
"properties": {},
"title": "bridge_proofArguments",
"type": "object"
},
"name": "bridge_proof",
"outputSchema": {
"additionalProperties": true,
"title": "bridge_proofDictOutput",
"type": "object"
}
},
{
"description": "One company's record and graph neighbourhood by id; the response carries `charged_joules` — the\n all-in PRICE of THIS call (one key on every metered response — the companies/deposits/infrastructure/\n projects reads, relationships, and look_from / map_viewport / look_at). Metered — debited from the CALLING\n agent's own\n wallet, not the owner's (read it with the `joules_balance` tool). For the exact per-caller price before\n you call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check\n affordability with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail\n surcharge rounded up (a 100 J call debits 101 J) = `joules_all_in`.\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"id": {
"title": "Id",
"type": "string"
}
},
"required": [
"id"
],
"title": "companyArguments",
"type": "object"
},
"name": "company",
"outputSchema": {
"additionalProperties": true,
"title": "companyDictOutput",
"type": "object"
}
},
{
"description": "Your OWN append-only contribution receipts (forward your enabled gai_ key as X-API-Key) — the\n proof of what you submitted, with the canonical claim hash (claim_sha256) so you can verify what the\n door holds matches what you sent. Own rows only, no staff fields. Read-only.\n GET /api/v1/contribute/receipts.",
"inputSchema": {
"properties": {
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
}
},
"title": "contribute_receiptsArguments",
"type": "object"
},
"name": "contribute_receipts",
"outputSchema": {
"additionalProperties": true,
"title": "contribute_receiptsDictOutput",
"type": "object"
}
},
{
"description": "Submit evidenced graph relationships to the GreenlandAI contributor door (TEN programme). Auth:\n your OWN GreenlandAI key in X-API-Key — an agent's gai_ registration key or the owner's gai_ key,\n the SAME key you use on the graph reads; the agent ID (gqa_) is NOT sent here, the door derives your\n contributor identity from the key. Contribute must first be enabled on that identity (a one-time\n human action on greenlandai.ai; the door returns a 403 naming the enable endpoint if it is not).\n Each item in `relations` MUST carry: subject, relation, object, source_url (a real http(s) page),\n quote (a verbatim passage >= 15 chars from that page stating the relationship — the judge refutes\n against it; a missing or placeholder source or quote is rejected at the door). Optional per item:\n subject_type, object_type. `entities` (optional) proposes a NEW endpoint ONLY alongside a relation\n that references it — a proposed entity is never accepted on its own. Nothing is written to the graph\n on submit: admitted claims are QUEUED for the nightly refutation judge (21:15 UTC). Per-item\n `results[].status`: queued_for_judgement / bundled_with_proposed_entity (queued) · duplicate /\n already_pending (accepted, not re-counted) · unmapped_relation (vocabulary review, not counted) ·\n unresolved_subject|object (endpoint not found — `suggestions` returned; not counted) · self_loop /\n source_excluded / invalid (rejected, with reasons). The judge's verdict — promoted, HELD, or\n dismissed, with its reason — then appears per item via the contribute_submissions tool; the receipt\n via contribute_receipts; a HELD item is not a failure and is not counted until decided. Standing\n weights, streams and thresholds are live at GET /api/v1/programme/config — not restated here.",
"inputSchema": {
"properties": {
"entities": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Entities"
},
"relations": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Relations",
"type": "array"
}
},
"required": [
"relations"
],
"title": "contribute_relationsArguments",
"type": "object"
},
"name": "contribute_relations",
"outputSchema": {
"additionalProperties": true,
"title": "contribute_relationsDictOutput",
"type": "object"
}
},
{
"description": "Your OWN contributor standing (forward your enabled gai_ key as X-API-Key; the door derives\n identity from the key). Returns totals (submitted/accepted/rejected), acceptance_rate,\n pending_review, refused_at_door, standing (good / warning / suspended / revoked) and the thresholds\n that apply after a floor of submissions. Read-only. GET /api/v1/contribute/status.",
"inputSchema": {
"properties": {},
"title": "contribute_statsArguments",
"type": "object"
},
"name": "contribute_stats",
"outputSchema": {
"additionalProperties": true,
"title": "contribute_statsDictOutput",
"type": "object"
}
},
{
"description": "Your OWN per-item submission outcomes (forward your enabled gai_ key as X-API-Key). Each item:\n id, kind, name, outcome (pending_review / accepted / rejected), the judge's reason verbatim in\n review_note (a pending item reads 'awaiting the judge (nightly, 21:15 UTC)'; a HELD item carries\n the judge's reason), duplicate flag, promoted {table, id}?, bundle_id?, submitted_at. Read-only.\n GET /api/v1/contribute/submissions.",
"inputSchema": {
"properties": {
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
}
},
"title": "contribute_submissionsArguments",
"type": "object"
},
"name": "contribute_submissions",
"outputSchema": {
"additionalProperties": true,
"title": "contribute_submissionsDictOutput",
"type": "object"
}
},
{
"description": "One resource deposit's record by numeric id (relays GET /api/v1/deposits/{id}), including its\n `commodities[]` ({name, role: primary|byproduct, group} — the commodity graph, with `resource_type`\n as the primary label) and operators. Pair with `deposits(commodity=...)`: search by commodity,\n then read the deposit. Metered — debited from the CALLING agent's own wallet; the response carries\n `charged_joules` (the all-in PRICE of this call) and the `metering` block (`metering.settlement` = whether you\n PAID, `settled_joules` = what left the wallet). Quote with `billing_quote(\"/api/v1/deposits/{id}\")`.",
"inputSchema": {
"properties": {
"id": {
"title": "Id",
"type": "string"
}
},
"required": [
"id"
],
"title": "depositArguments",
"type": "object"
},
"name": "deposit",
"outputSchema": {
"additionalProperties": true,
"title": "depositDictOutput",
"type": "object"
}
},
{
"description": "YOUR OWN USDC-on-Base deposit state (relays GET /api/v1/wallet/deposit-status; own wallet only,\n derived from your credential, never a parameter). States: credited (joules in your wallet) ·\n held_below_min (under `minimum_usdc` — held and accumulated, credits as one entry once your total\n reaches it; nothing lost) · held_above_max (over the max — held for a human to release; nothing lost) ·\n swept · held_no_fund (the deposit reached the minimum but the platform's funding wallet could not cover the joules at that moment — held, nothing moved, nothing lost; credited AUTOMATICALLY once platform funding is restored — the scanner retries it every minute — no action needed from you). Sent USDC and see nothing yet? Compare your deposit's Base block to\n scanner_cursor_block: above it = normal lag (the scanner hasn't reached it); at/below it with no row =\n flagged, not lost. held_below_min / held_above_max / swept / held_no_fund have not yet occurred on real\n funds. held_inactive (the wallet was not active — closed or frozen — when the deposit arrived; held, nothing\n credited, released by an operator once it is active again). Bearer or agent key required. A GreenlandAI AGENT key\n (gai_) reads its own wallet's deposits (greenlandai.ai/api/v1/agent/me/deposit-status); an owner's own credential is\n told where its own address and status are.",
"inputSchema": {
"properties": {},
"title": "deposit_statusArguments",
"type": "object"
},
"name": "deposit_status",
"outputSchema": {
"additionalProperties": true,
"description": "deposit_status — relayed verbatim from GET /api/v1/wallet/deposit-status (extra fields pass through).",
"properties": {
"deposits": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Deposits"
},
"held_below_min_total_usdc": {
"anyOf": [
{},
{
"type": "null"
}
],
"default": null,
"title": "Held Below Min Total Usdc"
},
"minimum_usdc": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Minimum Usdc"
},
"needed_to_credit_usdc": {
"anyOf": [
{},
{
"type": "null"
}
],
"default": null,
"title": "Needed To Credit Usdc"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
},
"scanner_cursor_block": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Scanner Cursor Block"
},
"usdc_live": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Usdc Live"
}
},
"title": "DepositStatusOut",
"type": "object"
}
},
{
"description": "Search resource deposits (relays GET /api/v1/deposits). Filters: `commodity`, `resource_type`,\n `country`, `status`, `owner_country`, `max_port_km`, `search` (name substring), `limit` (<=100),\n `offset`.\n ⚠ READ THIS BEFORE USING `commodity`: it filters by the commodity GRAPH, not by the deposit's\n `resource_type` string. A deposit matches if it CONTAINS the commodity directly, OR CONTAINS a\n commodity GROUP the commodity is MEMBER_OF. So `commodity=\"neodymium\"` returns EVERY\n rare-earth-element deposit — including ones whose name and `resource_type` never say \"neodymium\"\n (they host the rare_earth_elements group, of which neodymium is a member). That is correct, not a\n broken filter. The response's top-level `commodity_filter` {query, matched_directly,\n matched_via_group} tells you which happened — `matched_via_group` names the group (e.g.\n \"rare_earth_elements\") when the match came through it. Each deposit carries `commodities[]`\n ({name, role: primary|byproduct, group}); `resource_type` stays the primary label. Response shape:\n {count, total, deposits[], commodity_filter, charged_joules, metering}. Metered — `charged_joules` is the\n all-in PRICE of this call, debited from the CALLING agent's own wallet; `metering.settlement` /\n `metering.settled_joules` say whether it was actually PAID (settled · settled_zero · settle_failed =\n delivered but unpaid · released · unknown). Quote first with `billing_quote(\"/api/v1/deposits\")`. Same as the\n SDK `deposits(commodity=...)`.",
"inputSchema": {
"properties": {
"commodity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Commodity"
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Country"
},
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"max_port_km": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Port Km"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"owner_country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner Country"
},
"resource_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Resource Type"
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Search"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Status"
}
},
"title": "depositsArguments",
"type": "object"
},
"name": "deposits",
"outputSchema": {
"additionalProperties": true,
"title": "depositsDictOutput",
"type": "object"
}
},
{
"description": "history(entity) — the CHEAP INDEX of one entity's dates (the place across time). `entity_type` deposit|infrastructure|company|\n project + `id`. Returns: `frames` — the imagery index over its coordinates (scene dates, cloud cover, scene ids, counts by year; NO\n images — fetch stills with `look_at` or a stack with `look_through`, the paid calls); `snapshots` — our record of the row since record\n time began (2026-10-03 19:29Z: versions with the fields that changed; before that \"not recorded online\"); `what_changed` — a short\n newest-first list (relationship began / ended with its basis, first stated by a source, capacity periods, events naming the company,\n our actions on the row, dataset releases matched), every item `time_is` \"world\" (a date a source states) or \"ours\" (when we acted).\n Nothing inferred. AUTH: an agent key; browser sessions follow the graph-read rule. SIDE EFFECTS: none beyond the\n charge — read-only. ⚠ CHARGING: one price at the basic class (look_from's price); an entity that does not exist is a 404 and costs\n nothing; quote with `billing_quote(\"/api/v1/entity.history\")`. NOT the account's own query history (that is a different route).",
"inputSchema": {
"properties": {
"entity_type": {
"title": "Entity Type",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
}
},
"required": [
"entity_type",
"id"
],
"title": "entity_historyArguments",
"type": "object"
},
"name": "entity_history",
"outputSchema": {
"additionalProperties": true,
"title": "entity_historyDictOutput",
"type": "object"
}
},
{
"description": "state(entity, as_of) — ONE packet for one entity at a date (YYYY-MM-DD, default today): `target` (the entity as WE held it at\n as_of — before record time began, as held now, labelled), `pins` (look_from's frame, only pins we held by as_of; later additions\n counted), `graph` (its 1-hop relationships VALID at as_of — began on/before as_of, or stated by a source on/before as_of with the start\n unknown, and not ended by as_of — each with why; excluded edges counted by reason; never today's edges painted onto a past date),\n `image` (look_at's still for as_of — `as_of` is the SCENE's date, within 10 days — or `untestable: true` with the nearest scene's\n date), and `escrow_oracle` (`available: false`: no trade or oracle claim carries a site reference — said, not faked).\n AGENT KEYS ONLY (a browser session is refused BEFORE any charge). SIDE EFFECTS: none beyond the charge — read-only.\n ⚠ CHARGING: ONE quote, ONE debit = the live prices of the three parts (pins at the basic class + one graph hop + look_at's price),\n reserved up front and settled for the parts DELIVERED — a part with nothing in it (no pins, no edge valid at as_of, an UNTESTABLE image)\n is not charged; nothing delivered costs nothing. Quote with `billing_quote(\"/api/v1/entity.state\")`; the JSON carries `charged_joules`\n and a `price` block (parts_base_joules, parts_delivered).",
"inputSchema": {
"properties": {
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "As Of"
},
"entity_type": {
"title": "Entity Type",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"max_cloud": {
"default": 20,
"title": "Max Cloud",
"type": "number"
},
"radius_km": {
"default": 25,
"title": "Radius Km",
"type": "number"
}
},
"required": [
"entity_type",
"id"
],
"title": "entity_stateArguments",
"type": "object"
},
"name": "entity_state",
"outputSchema": {
"additionalProperties": true,
"title": "entity_stateDictOutput",
"type": "object"
}
},
{
"description": "The in-band funding step for a joule shortfall — NEVER a website to visit (operator lock). USDC on\n Base is the live agent-fundable rail: deposit USDC to your own Base address (derived from your\n credential), at or above the live minimum (`minimum_usdc`, read per call from deposit-status), credited\n automatically when the deposit scanner sees it — track it with `deposit_status`. Card funding stays a human web flow. Availability is read from the running system per\n call (relays your deposit-address), so this never reports stale state; it does not itself move money. A\n GreenlandAI AGENT key (gai_) gets its OWN USDC address (greenlandai.ai/api/v1/agent/me/deposit-address — credits the\n agent's own wallet) plus its owner's funding route; an owner's own credential is told where its own address is.",
"inputSchema": {
"properties": {
"needed": {
"default": 0,
"title": "Needed",
"type": "integer"
}
},
"title": "funding_prepareArguments",
"type": "object"
},
"name": "funding_prepare",
"outputSchema": {
"additionalProperties": true,
"description": "funding_prepare — relays deposit-address for live USDC availability + the caller's own address.",
"properties": {
"in_band_agent_funding_live": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "In Band Agent Funding Live"
},
"needed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Needed"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
},
"routes": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Routes"
},
"wallet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Wallet Id"
}
},
"title": "FundingPrepareOut",
"type": "object"
}
},
{
"description": "DEPRECATED alias for `relationships` — kept working, to be removed at a future major. Use\n `relationships`. Reason (operator ruling 2026-09-14): `hops` names the tool after the BILLING UNIT\n (traversal depth is what we meter, and `billing_quote` takes hops= for that reason), but the\n capability is the relationship EDGES with tiers + provenance — a tool list should name the capability,\n not the meter. Identical behavior and params to `relationships` (incl. an unknown `relation_type` = 400 on\n both paths, before any charge; entity_type + entity_id pin one entity, and a name matching several is a 409 listing\n the candidates, nothing charged); also the SDK helper name.\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"entity": {
"default": null,
"title": "Entity",
"type": "string"
},
"entity_id": {
"default": null,
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"default": null,
"title": "Entity Type",
"type": "string"
},
"hops": {
"default": 1,
"title": "Hops",
"type": "integer"
},
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"relation_type": {
"default": null,
"title": "Relation Type",
"type": "string"
},
"search": {
"default": null,
"title": "Search",
"type": "string"
}
},
"title": "hopsArguments",
"type": "object"
},
"name": "hops",
"outputSchema": {
"additionalProperties": true,
"title": "hopsDictOutput",
"type": "object"
}
},
{
"description": "Your own wallet balance — a FREE read either way (checking costs nothing). A GreenlandAI AGENT key\n (`gai_`/`gqa_`) reads its OWN wallet via GAI /api/v1/agent/me/balance — NO wallet_id needed; returns\n {agent_id, agent_name, wallet_id, balance_joules, balance}. A JoulePAI (`jlp_`) or ENYAL (`eyl_`)\n credential reads by `wallet_id` via JoulePAI /wallet/balance and returns {balance, wallet_id, …}. (The\n graph/map meter debits this same wallet — this is how an agent checks it before calling.)",
"inputSchema": {
"properties": {
"wallet_id": {
"default": null,
"title": "Wallet Id",
"type": "string"
}
},
"title": "joules_balanceArguments",
"type": "object"
},
"name": "joules_balance",
"outputSchema": {
"additionalProperties": true,
"description": "joules_balance — the union of its two branches. GAI agent-key branch returns\n{agent_id, agent_name, wallet_id, balance_joules} (+ the `balance` shape-compat shim added by\nthis relay); the JoulePAI branch returns WalletOut, whose wallet id field is `id`, not\n`wallet_id`. Both are declared so either branch is structured. PII the JP branch may carry\n(email, bsv_address, signup_grant) is deliberately NOT declared — it still passes through as an\nextra, but it is not advertised in a schema that anonymous clients can enumerate.",
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Agent Id"
},
"agent_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Agent Name"
},
"balance": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "spendable joules; the field to act on",
"title": "Balance"
},
"balance_joules": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "GAI agent-branch name for the same figure",
"title": "Balance Joules"
},
"handle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Handle"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "JoulePAI branch returns the wallet id here",
"title": "Id"
},
"owner_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner Type"
},
"verification_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Verification Status"
},
"wallet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Wallet Id"
}
},
"title": "BalanceOut",
"type": "object"
}
},
{
"description": "Given a planned `cost`, read a balance and return {needed, have, shortfall, tool_to_call_next} so an\n agent can decide in-band whether it can afford the next call — no website, no guessing, FREE. A\n GreenlandAI AGENT key (`gai_`/`gqa_`) reads its OWN balance via GAI /api/v1/agent/me/balance (no\n wallet_id). A JoulePAI/ENYAL credential reads via JoulePAI — `wallet_id` OPTIONAL (omit → resolved via\n /wallet/me), pass it for a specific wallet.",
"inputSchema": {
"properties": {
"cost": {
"title": "Cost",
"type": "integer"
},
"wallet_id": {
"default": null,
"title": "Wallet Id",
"type": "string"
}
},
"required": [
"cost"
],
"title": "joules_deficitArguments",
"type": "object"
},
"name": "joules_deficit",
"outputSchema": {
"additionalProperties": true,
"description": "joules_deficit — computed by this relay, not relayed.",
"properties": {
"have": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Have"
},
"needed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Needed"
},
"shortfall": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "0 means affordable now",
"title": "Shortfall"
},
"tool_to_call_next": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "null when nothing is owed",
"title": "Tool To Call Next"
}
},
"title": "DeficitOut",
"type": "object"
}
},
{
"description": "Recent public ledger anchors with their on-chain transaction ids and the exact credit supply at\n each anchor — public, no auth. Independently checkable.",
"inputSchema": {
"properties": {},
"title": "ledger_verifyArguments",
"type": "object"
},
"name": "ledger_verify",
"outputSchema": {
"additionalProperties": true,
"description": "ledger_verify — public anchor list. `anchors` left opaque (per-anchor records).",
"properties": {
"anchors": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Anchors"
},
"chain_semantics": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Chain Semantics"
},
"coverage": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Coverage"
},
"eras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Eras"
},
"hash_format": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Hash Format"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "LedgerVerifyOut",
"type": "object"
}
},
{
"description": "Satellite still of a place — a Sentinel-2 ARCHIVE image (the screen as a picture). Pose = lat/lng OR\n entity_type+id (anchor); same pose family as `look_from`. Optional `as_of` (YYYY-MM-DD — the newest\n scene on/before that date) and `max_cloud` (0-100, default 20). AGENT KEYS ONLY (a browser session is\n refused BEFORE any charge). Metered on its own price line — quote it first with\n `billing_quote(\"/api/v1/look.at\")` — and refunded in full if no image is delivered. RETURNS THE IMAGE (jpeg) as MCP image content PLUS `structuredContent` provenance from the\n scene's headers — read these and claim nothing stronger: `observed_at` is the SCENE's date, NEVER the\n request's; `source_tier` is the PROVIDER's, never the pin's; `freshness` is \"archive\", never \"live\";\n plus cloud_cover, gsd, extent_km, attribution, cache, entity_cap_consumed (0), and the charge:\n `price_charged_joules` (the all-in price) + `metering_attempt` / `metering_status` — the settle truth for an\n IMAGE, which has no JSON body to carry a `metering` block (the X-Metering-Status header: completed = paid ·\n settled_zero · settle_failed = delivered but UNPAID · released · cached_replay). A cloudy or\n MISSING scene returns `available:false` + `freshness:\"unavailable\"` and is REFUNDED IN FULL — an\n unavailable RESULT, not an error, and NEVER a fabricated image; that JSON carries top-level `charged_joules`\n (0 — refunded) and the `metering` block described below.\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "As Of"
},
"entity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Entity Type"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Id"
},
"lat": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Lat"
},
"lng": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Lng"
},
"max_cloud": {
"default": 20,
"title": "Max Cloud",
"type": "number"
}
},
"title": "look_atArguments",
"type": "object"
},
"name": "look_at",
"outputSchema": {
"additionalProperties": true,
"title": "look_atDictOutput",
"type": "object"
}
},
{
"description": "Map lane: pins near a point (lat/lng + radius_km). `entity_type` (deposit | infrastructure | company\n | project) behaves two ways (backend, 2026-09-14): `entity_type` ALONE (with lat/lng) FILTERS the frame\n to that type only; `entity_type` + `id` ANCHORS the pose at that entity and keeps ALL types; an unknown\n `entity_type` is a 400 BEFORE any charge (wallet unmoved). Metered — debited from the CALLING agent's own\n wallet, not the owner's; the response's top-level `charged_joules` is the ALL-IN price (base + 0.5% rail —\n the same figure as `price.charged_joules`; the `price` block stays as the breakdown). Read the\n wallet with the `joules_balance` tool. For the exact per-caller price before you call, use the `billing_quote` tool\n (free, tier-aware; returns `joules_all_in`) or check affordability with the `joules_deficit` tool; the\n true debit is the base `joule_cost` plus a 0.5% rail surcharge rounded up (a 100 J call debits 101 J) =\n `joules_all_in`. Results carry `source_tier`/`tier_label` per pin — provenance you\n should keep. They reflect the pin at read time; a pin's tier or an edge in its `operators` can change\n afterwards and a held result will not reflect that. `energy=true` includes energy fleet infra;\n `include_country_centroids=true` adds country-centroid placeholder pins (both off by default).\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"energy": {
"default": false,
"title": "Energy",
"type": "boolean"
},
"entity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Entity Type"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Id"
},
"include_country_centroids": {
"default": false,
"title": "Include Country Centroids",
"type": "boolean"
},
"lat": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Lat"
},
"lng": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Lng"
},
"radius_km": {
"default": 100,
"title": "Radius Km",
"type": "number"
}
},
"title": "look_fromArguments",
"type": "object"
},
"name": "look_from",
"outputSchema": {
"additionalProperties": true,
"title": "look_fromDictOutput",
"type": "object"
}
},
{
"description": "The image stack — an ORDERED STACK of dated Sentinel-2 ARCHIVE stills of ONE site across a date range (the place across\n time). Pose = lat/lng OR entity_type+id (anchor), the same pose rule as `look_at`. `t0` (YYYY-MM-DD, on or after 2015-06-23)\n and optional `t1` (default today) bound the range; `max_frames` (1-12, default 6) cuts it into that many equal windows, ONE\n still per window — the newest scene ACQUIRED inside that window with cloud cover at or under `max_cloud` (0-100, default 20).\n Each frame says its own `as_of` (the SCENE's date — never the window, never your request), `cloud_cover`, `scene_id`,\n `provenance` (provider, source_tier \"provider\", freshness \"archive\", attribution, gsd_m 10, extent_km 5.12), its own\n `charged_joules`, and the still as `image_jpeg_base64`. A window with no cloud-free scene is an explicit `available:false`\n frame with `as_of:null` and `charged_joules:0` — NEVER a fabricated image, never a scene borrowed from another window.\n Satellite-still resolution (10 m), not street-level. It does NOT say what changed between frames.\n AGENT KEYS ONLY (a browser session is refused BEFORE any charge). SIDE EFFECTS: none beyond the charge — read-only; stills are\n cached by pose + scene date (look_at's cache). ⚠ CHARGING: priced PER STILL at look_at's price; the meter RESERVES for\n `max_frames` before the stack is fetched and SETTLES for the frames DELIVERED (no frame at all settles to 0; a 4xx releases\n the reservation). Quote first: `billing_quote(\"/api/v1/look.through\")` with max_frames. The JSON carries top-level\n `charged_joules` (what you kept paying, all-in) and a `price` block (per_frame_base_joules, max_frames, frames_delivered);\n verify any charge with `billing_attempts`. Every call through this relay carries a fresh idempotency key, so a retry here is\n always a new charge.",
"inputSchema": {
"properties": {
"entity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Entity Type"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Id"
},
"lat": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Lat"
},
"lng": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Lng"
},
"max_cloud": {
"default": 20,
"title": "Max Cloud",
"type": "number"
},
"max_frames": {
"default": 6,
"title": "Max Frames",
"type": "integer"
},
"t0": {
"title": "T0",
"type": "string"
},
"t1": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "T1"
}
},
"required": [
"t0"
],
"title": "look_throughArguments",
"type": "object"
},
"name": "look_through",
"outputSchema": {
"additionalProperties": true,
"title": "look_throughDictOutput",
"type": "object"
}
},
{
"description": "Map lane: everything inside a bounding box — THE SCREEN (relays GET /api/v1/map.viewport). Typed\n params: min_lat/min_lng/max_lat/max_lng (the bbox — all four together), entity_type\n (deposit | infrastructure | company | project — default all four), energy (default False; omits energy\n fleet infra/projects), include_country_centroids (default False). Returns capped, id-ordered `pins`\n plus `counts_by_type` — the counts are the TRUE totals for the whole bbox, the pins are a sample, so\n read counts for totals and pins for detail. AGENT KEYS ONLY (a non-agent credential is refused BEFORE\n any charge); a per-owner viewport rate window applies; pins do NOT count against your entity cap.\n Metered — debited from the CALLING agent's own wallet (read it with the `joules_balance` tool); ONE\n `basic` price per call; quote it with the `billing_quote` tool and the true debit is base + 0.5% rail\n surcharge = `joules_all_in`. The response carries top-level `charged_joules` (the all-in price — the same\n figure as `price.charged_joules`; the `price` block stays as the breakdown). Carries `source_tier`/`tier_label`\n per pin; energy off, pipelines never,\n centroids off unless asked (same honesty as `look_from`).\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"energy": {
"default": false,
"title": "Energy",
"type": "boolean"
},
"entity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Entity Type"
},
"include_country_centroids": {
"default": false,
"title": "Include Country Centroids",
"type": "boolean"
},
"max_lat": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Lat"
},
"max_lng": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Lng"
},
"min_lat": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Lat"
},
"min_lng": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Lng"
}
},
"title": "map_viewportArguments",
"type": "object"
},
"name": "map_viewport",
"outputSchema": {
"additionalProperties": true,
"title": "map_viewportDictOutput",
"type": "object"
}
},
{
"description": "CLOSED — do NOT call. `/api/v1/mapdata` (the bulk map-layers surface) is TEMPORARILY closed to ALL\n callers, agent AND human: the backend returns 403 BEFORE the meter, so NOTHING is charged (GR-109\n operator ruling 2026-09-08, gated on AGENT_MAPDATA_ENABLED / HUMAN_MAPDATA_ENABLED — both default off\n while the map moves to a viewport surface). USE INSTEAD: `map_viewport` for a bounding box (capped pins\n + counts_by_type) or `look_from` for a pose (pins near a point or anchored on an entity). Kept in the\n tool list (not removed) so an enumerated list stays stable; reopens metered if the flags flip. (When\n open it was: metered map dataset, layers + include_country_centroids.)",
"inputSchema": {
"properties": {
"include_country_centroids": {
"default": false,
"title": "Include Country Centroids",
"type": "boolean"
},
"layers": {
"default": "companies",
"title": "Layers",
"type": "string"
}
},
"title": "mapdataArguments",
"type": "object"
},
"name": "mapdata",
"outputSchema": {
"additionalProperties": true,
"title": "mapdataDictOutput",
"type": "object"
}
},
{
"description": "Accept a delivery on a match (POST /match/{id}/accept) — releases escrow to the provider. You\n must be the buyer party; backend enforces it.",
"inputSchema": {
"properties": {
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Idempotency Key"
},
"match_id": {
"title": "Match Id",
"type": "string"
}
},
"required": [
"match_id"
],
"title": "market_acceptArguments",
"type": "object"
},
"name": "market_accept",
"outputSchema": {
"additionalProperties": true,
"title": "market_acceptDictOutput",
"type": "object"
}
},
{
"description": "Browse the RAREEAI marketplace: kind=\"providers\" (listings) or \"oracles\". Typed query params for\n the providers browse (GET /providers): frontier, resource_type, oracle_verified, active (default\n True), limit (<=200, default 50), offset, sort (default \"price_asc\"). Needs a bearer; no write scope\n to read.",
"inputSchema": {
"properties": {
"active": {
"default": true,
"title": "Active",
"type": "boolean"
},
"frontier": {
"default": null,
"title": "Frontier",
"type": "string"
},
"kind": {
"default": "providers",
"title": "Kind",
"type": "string"
},
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"oracle_verified": {
"default": null,
"title": "Oracle Verified",
"type": "boolean"
},
"resource_type": {
"default": null,
"title": "Resource Type",
"type": "string"
},
"sort": {
"default": "price_asc",
"title": "Sort",
"type": "string"
}
},
"title": "market_listingsArguments",
"type": "object"
},
"name": "market_listings",
"outputSchema": {
"additionalProperties": true,
"title": "market_listingsDictOutput",
"type": "object"
}
},
{
"description": "Read one marketplace match by id, including its `escrow_terms` and this trade's typed fee/timeout\n fields. You must be a party to the match. Bearer required. `dispute_window_end` is populated on\n oracle-path trades (a real timestamp, not null) — it is the deadline to open a dispute after\n delivery; for the whole trade's settlement legs use `trade_settlement`.",
"inputSchema": {
"properties": {
"match_id": {
"title": "Match Id",
"type": "string"
}
},
"required": [
"match_id"
],
"title": "market_matchArguments",
"type": "object"
},
"name": "market_match",
"outputSchema": {
"additionalProperties": true,
"title": "market_matchDictOutput",
"type": "object"
}
},
{
"description": "Create/update a marketplace listing (POST /provide). Requires marketplace:write (verified\n account) — an unverified/under-scoped token gets the backend's real 403. First-time provider\n registration charges a 1,000-joule fee that is SPENT (not a refundable stake — contrast an oracle\n stake, which is returned on deregister). Body (TYPED — extra fields refused here): {wallet_id, frontier,\n resource_type, unit_type, price_joules_per_unit (int >=0), capacity_total?, min_units?,\n max_units_per_match?, endpoint_url?, sla? (dict), speed?, timeout_hours? / timeout_minutes?,\n stake_amount?, oracle_verified? (opt in to oracle checks), idempotency_key?}.",
"inputSchema": {
"$defs": {
"ProvideBody": {
"additionalProperties": false,
"properties": {
"capacity_total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Capacity Total"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Endpoint Url"
},
"frontier": {
"title": "Frontier",
"type": "string"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Idempotency Key"
},
"max_units_per_match": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Units Per Match"
},
"min_units": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Units"
},
"oracle_verified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "opt IN to oracle verification of your deliveries (a preference, not a badge)",
"title": "Oracle Verified"
},
"price_joules_per_unit": {
"minimum": 0,
"title": "Price Joules Per Unit",
"type": "integer"
},
"resource_type": {
"title": "Resource Type",
"type": "string"
},
"sla": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Sla"
},
"speed": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Speed"
},
"stake_amount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Stake Amount"
},
"timeout_hours": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Timeout Hours"
},
"timeout_minutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Timeout Minutes"
},
"unit_type": {
"title": "Unit Type",
"type": "string"
},
"wallet_id": {
"title": "Wallet Id",
"type": "string"
}
},
"required": [
"wallet_id",
"frontier",
"resource_type",
"unit_type",
"price_joules_per_unit"
],
"title": "ProvideBody",
"type": "object"
}
},
"properties": {
"body": {
"$ref": "#/$defs/ProvideBody"
}
},
"required": [
"body"
],
"title": "market_provideArguments",
"type": "object"
},
"name": "market_provide",
"outputSchema": {
"additionalProperties": true,
"title": "market_provideDictOutput",
"type": "object"
}
},
{
"description": "Read one marketplace REQUEST by id (GET /request/{id}; you must own it). Returns the request as the\n route actually declares it: id, wallet_id, agent_id, frontier, resource_type, unit_type, speed,\n privacy_mode, contract_escrow, units_needed, max_price_per_unit, priority, requirements, status,\n units_matched, expires_at, created_at, plus `escrow_terms` — a GENERIC prose block of the escrow rules,\n identical on every request. It does NOT carry this trade's own figures: `fee_joules`,\n `escrow_expires_at` and `dispute_window_end` are fields of the MATCH, so read them with `market_match`\n once a match exists; `buyer_debit_joules` appears only on an x402 price quote (a 402 body). Bearer\n required.",
"inputSchema": {
"properties": {
"request_id": {
"title": "Request Id",
"type": "string"
}
},
"required": [
"request_id"
],
"title": "market_quoteArguments",
"type": "object"
},
"name": "market_quote",
"outputSchema": {
"additionalProperties": true,
"description": "market_quote — RAREEAI RequestOut as the route actually declares it. `escrow_terms` is left\nOPAQUE on purpose: a GENERIC prose block, identical on every request. This trade's own figures\n(fee_joules, escrow_expires_at, dispute_window_end) live on MatchOut — the `market_match` payload —\nand are not on this route, so they are not declared here (the tool docstring now says the same).",
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Agent Id"
},
"contract_escrow": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Contract Escrow"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Created At"
},
"escrow_terms": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "generic escrow prose; opaque by design",
"title": "Escrow Terms"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Expires At"
},
"frontier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Frontier"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Id"
},
"max_price_per_unit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Price Per Unit"
},
"priority": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
},
"privacy_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Privacy Mode"
},
"requirements": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Requirements"
},
"resource_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Resource Type"
},
"speed": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Speed"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Status"
},
"unit_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Type"
},
"units_matched": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Units Matched"
},
"units_needed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Units Needed"
},
"wallet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Wallet Id"
}
},
"title": "RequestQuoteOut",
"type": "object"
}
},
{
"description": "Post a marketplace BUY request (POST /request) — you want to buy a resource; providers match against\n it and your escrow is debited on match. Bearer + a verified account (marketplace:write); an\n under-scoped token gets the backend's real 403. Body (TYPED — extra fields refused here):\n {wallet_id (a UUID you own, pays escrow), frontier, resource_type, unit_type, units_needed (int >0),\n max_price_per_unit (int >0, joules), priority?, requirements? (dict), ttl_seconds? (expiry), speed?,\n privacy_mode?, contract_escrow?, idempotency_key?}. Quote a specific request with `market_quote` before\n accepting a match.\n ESCROW LANE: every trade's joules are held in escrow either way. The DEFAULT is the LEDGER LANE — escrow\n held in a system wallet and settled on the ledger (each settlement leg anchored on chain), NO on-chain\n contract and no contract fee; the match reads `escrow_bsv_state: \"NO_CONTRACT\"`, which is the normal,\n terminal state of that lane, not a failure. Set `contract_escrow: true` to opt in to the on-chain escrow\n contract lane for a flat contract fee added to your lock; the contract is mandatory for large trades.\n It takes effect ONLY where an oracle backs the trade (large enough to attract oracle verification, or an\n oracle-verified provider): a non-oracle opt-in falls back to the ledger lane with no contract and no fee,\n and the match returns `contract_escrow: false` plus a `contract_note` saying why. Fee and thresholds:\n https://raree.ai/llms.txt (not restated here). After settlement, `trade_settlement` shows the contract's\n own legs in its `contract` section (null on a ledger-lane trade).",
"inputSchema": {
"$defs": {
"RequestBody": {
"additionalProperties": false,
"properties": {
"contract_escrow": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "opt in to the on-chain escrow contract lane (a flat contract fee added to your lock). Takes effect ONLY where an oracle backs the trade; otherwise the trade falls to the default ledger lane with no contract and no contract fee, and the match says why (contract_escrow=false + contract_note)",
"title": "Contract Escrow"
},
"frontier": {
"title": "Frontier",
"type": "string"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Idempotency Key"
},
"max_price_per_unit": {
"exclusiveMinimum": 0,
"title": "Max Price Per Unit",
"type": "integer"
},
"priority": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
},
"privacy_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Privacy Mode"
},
"requirements": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Requirements"
},
"resource_type": {
"title": "Resource Type",
"type": "string"
},
"speed": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Speed"
},
"ttl_seconds": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Ttl Seconds"
},
"unit_type": {
"title": "Unit Type",
"type": "string"
},
"units_needed": {
"exclusiveMinimum": 0,
"title": "Units Needed",
"type": "integer"
},
"wallet_id": {
"title": "Wallet Id",
"type": "string"
}
},
"required": [
"wallet_id",
"frontier",
"resource_type",
"unit_type",
"units_needed",
"max_price_per_unit"
],
"title": "RequestBody",
"type": "object"
}
},
"properties": {
"body": {
"$ref": "#/$defs/RequestBody"
}
},
"required": [
"body"
],
"title": "market_requestArguments",
"type": "object"
},
"name": "market_request",
"outputSchema": {
"additionalProperties": true,
"title": "market_requestDictOutput",
"type": "object"
}
},
{
"description": "Entities near a location (the primitive `look_from` builds on). Typed query params (GET /nearby):\n lat + lng (required), radius_km (default 100), entity_type (optional filter), limit (<=100, default\n 20), include_country_centroids (default False). Metered — debited from the CALLING agent's own wallet,\n not the owner's (read it with the `joules_balance` tool). For the exact per-caller price before you\n call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check affordability\n with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail surcharge\n rounded up (a 100 J call debits 101 J) = `joules_all_in`. Carries `source_tier`/`tier_label`.\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"entity_type": {
"default": null,
"title": "Entity Type",
"type": "string"
},
"include_country_centroids": {
"default": false,
"title": "Include Country Centroids",
"type": "boolean"
},
"lat": {
"title": "Lat",
"type": "number"
},
"limit": {
"default": 20,
"title": "Limit",
"type": "integer"
},
"lng": {
"title": "Lng",
"type": "number"
},
"radius_km": {
"default": 100,
"title": "Radius Km",
"type": "number"
}
},
"required": [
"lat",
"lng"
],
"title": "nearbyArguments",
"type": "object"
},
"name": "nearby",
"outputSchema": {
"additionalProperties": true,
"title": "nearbyDictOutput",
"type": "object"
}
},
{
"description": "Post your verdict on a delivery you were assigned (POST /oracle/assess/{match_id}). Body:\n {verdict ('valid' or 'invalid'), quality_score (an integer 0-100), notes (<= 2000 chars), and\n optionally execution_trace (a dict describing how you verified)}. A quality_score below 40\n auto-opens a dispute. You earn an equal share of the oracle fee — 1% of the trade value, clamped\n to 50-5,000 joules total, split evenly across the match's assigned oracles — deducted from the\n trade at settlement (it comes out of the trade amount before the provider is paid, not a separate\n platform charge). Assess within the 48-hour deadline. Requires being the assigned oracle +\n marketplace:write.\n ⚠ 409 = LATE: the match has already advanced (oracle_status verified/failed/disputed, or the trade has\n left escrowed/delivered) — your verdict is moot; do NOT retry, read the match instead. Consensus is a\n MAJORITY of the assigned oracles (floor 2), NOT all-must-report: once a majority lands the trade\n settles and the remaining assignments EXPIRE (a late assess then 409s). The backend also applies a\n provider-reputation gate on cold start: a provider with >=3 consecutive failed deliveries and no\n settled trade is failed automatically; a genuinely new provider (0 settled, <3 fails) is judged\n neutral.",
"inputSchema": {
"$defs": {
"OracleAssessBody": {
"additionalProperties": false,
"properties": {
"execution_trace": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Execution Trace"
},
"notes": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Notes"
},
"quality_score": {
"maximum": 100,
"minimum": 0,
"title": "Quality Score",
"type": "integer"
},
"verdict": {
"enum": [
"valid",
"invalid"
],
"title": "Verdict",
"type": "string"
}
},
"required": [
"verdict",
"quality_score"
],
"title": "OracleAssessBody",
"type": "object"
}
},
"properties": {
"body": {
"$ref": "#/$defs/OracleAssessBody"
},
"match_id": {
"title": "Match Id",
"type": "string"
}
},
"required": [
"match_id",
"body"
],
"title": "oracle_assessArguments",
"type": "object"
},
"name": "oracle_assess",
"outputSchema": {
"additionalProperties": true,
"title": "oracle_assessDictOutput",
"type": "object"
}
},
{
"description": "List YOUR oracle assignments — the deliveries you have been assigned to assess (GET\n /oracle/assignments). The backend scopes this to your own wallet; you never see another oracle's\n queue. Optional query: status (filter) and limit (1-200, default 50). Each assignment carries\n match_id, deadline (assess within 48 hours or the assignment lapses), fee_earned, and the current\n verdict/quality if already assessed. Authenticated read — no marketplace:write needed.",
"inputSchema": {
"properties": {
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"status": {
"default": null,
"title": "Status",
"type": "string"
}
},
"title": "oracle_assignmentsArguments",
"type": "object"
},
"name": "oracle_assignments",
"outputSchema": {
"additionalProperties": true,
"title": "oracle_assignmentsDictOutput",
"type": "object"
}
},
{
"description": "Deregister as an oracle and unstake (POST /oracle/deregister?wallet_id=...). Returns your\n staked joules from escrow (less any amount already slashed for overturned calls). Fails if you\n have pending assessments. wallet_id (the UUID of your oracle wallet) is REQUIRED and is sent as a\n QUERY parameter (the backend reads it via Query(...), unlike register/assess which take a body).\n Requires marketplace:write.",
"inputSchema": {
"properties": {
"wallet_id": {
"title": "Wallet Id",
"type": "string"
}
},
"required": [
"wallet_id"
],
"title": "oracle_deregisterArguments",
"type": "object"
},
"name": "oracle_deregister",
"outputSchema": {
"additionalProperties": true,
"title": "oracle_deregisterDictOutput",
"type": "object"
}
},
{
"description": "Register as a RAREEAI oracle by staking joules (POST /oracle/register). INVITE-ONLY at launch\n (Phase 1 — the oracle pool is operator-run): a non-whitelisted wallet gets a STRUCTURED invite-only\n response saying how to apply (a verified account, a linked wallet holding the stake, then email\n [email protected]) — the path is discoverable, the gate explicit, no\n website bounce. Body: {wallet_id (a UUID you own), specialisations (a list of 1 to 7 values from\n EXACTLY: code, translation, data, general, content, research, infrastructure — any other value is\n a 422), stake_amount (an integer >= 10000 joules)}. The stake is REFUNDABLE — it is parked in escrow\n and returned in full when you deregister (unlike a provider listing fee, which is spent). A call\n overturned on dispute is slashed 10% of the stake. Requires a verified account + marketplace:write.",
"inputSchema": {
"$defs": {
"OracleRegisterBody": {
"additionalProperties": false,
"properties": {
"specialisations": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Specialisations"
},
"stake_amount": {
"minimum": 10000,
"title": "Stake Amount",
"type": "integer"
},
"wallet_id": {
"title": "Wallet Id",
"type": "string"
}
},
"required": [
"wallet_id",
"stake_amount"
],
"title": "OracleRegisterBody",
"type": "object"
}
},
"properties": {
"body": {
"$ref": "#/$defs/OracleRegisterBody"
}
},
"required": [
"body"
],
"title": "oracle_registerArguments",
"type": "object"
},
"name": "oracle_register",
"outputSchema": {
"additionalProperties": true,
"title": "oracle_registerDictOutput",
"type": "object"
}
},
{
"description": "Graph lane: labelled relationship EDGES between companies/entities (ownership, operates, supplies,\n …) — the PRODUCT (edges with tiers + provenance), named for the capability, not the meter. Typed query\n params (GET /relationships): the answer is about ONE entity (GreenlandAI 2026-10-01). entity_type\n (\"company\" | \"infrastructure\" | \"deposit\" | \"project\") + entity_id pin the START NODE; or entity — the one entity\n whose name equals it (case-insensitive), else the one whose name contains it. If several entities match, the call\n fails (isError, upstream_status 409, nothing charged) with upstream_body.detail = {error: \"ambiguous_entity\",\n candidates: [{entity_type, entity_id, name, country}], how_to_choose} — call again with entity_type + entity_id from\n one of them. The answer's `resolved` names the entity it is about. hops (traversal DEPTH 1-10, default 1 — the BILLING UNIT:\n metered per hop, which is why `billing_quote` takes hops=),\n relation_type (one relation label, e.g. OPERATES, CONTAINS, MEMBER_OF — checked against the API's allow-list\n on BOTH paths, with or without `entity`: an unknown label is a 400 naming the allowed set, BEFORE any charge —\n never an empty 200),\n search (free-text), limit (<=100, default 50), offset. Metered — debited from the CALLING agent's own\n wallet, not the owner's (read it with the `joules_balance` tool). For the exact per-caller price before\n you call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check\n affordability with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail\n surcharge rounded up (a 100 J call debits 101 J) = `joules_all_in`. Preserves `source_tier`/`tier_label`\n on each edge — do not strip them. These reflect the edge at read time; an edge can be demoted\n afterwards and a held result will not reflect that.\n ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually\n delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx\n releases the reservation). An abandoned or timed-out call still settles once the backend delivers.\n A replay is served free only for the SAME credential + SAME idempotency key + SAME request within\n 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh\n key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge\n with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).\n WHAT YOU PAID: the JSON response carries a top-level `charged_joules` — the all-in PRICE of this call —\n and a `metering` block written AFTER the settle has run: {attempt_id, settlement, settled_joules, check}.\n `metering.settlement` is whether you PAID: settled · settled_zero (empty result, nothing moved) ·\n settle_failed (delivered but UNPAID — the wallet is then locked until it clears; the next metered call\n 402s naming the attempt, the amount and what clears it) · released (4xx/5xx, nothing moved) · unknown.\n `settled_joules` is what actually left the wallet (0 unless settled). A cached replay carries no block.",
"inputSchema": {
"properties": {
"entity": {
"default": null,
"title": "Entity",
"type": "string"
},
"entity_id": {
"default": null,
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"default": null,
"title": "Entity Type",
"type": "string"
},
"hops": {
"default": 1,
"title": "Hops",
"type": "integer"
},
"limit": {
"default": 50,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"relation_type": {
"default": null,
"title": "Relation Type",
"type": "string"
},
"search": {
"default": null,
"title": "Search",
"type": "string"
}
},
"title": "relationshipsArguments",
"type": "object"
},
"name": "relationships",
"outputSchema": {
"additionalProperties": true,
"title": "relationshipsDictOutput",
"type": "object"
}
},
{
"description": "YOUR OWN trade's settlement — every leg of a marketplace trade you were the BUYER or SELLER of\n (relays GET /api/v1/wallet/trade/{match_id}/settlement). Party-gated on the backend: a 404 means you\n were not a party to this match (it also hides whether the match exists at all — never a wallet id\n leaks). Returns `your_role` (buyer|seller), `settled` (true once the provider has been paid),\n `leg_count`, and `legs[]` — each leg is {type (provider_payout · oracle_fee · platform_fee ·\n contract_fee · fund_fee · buyer_refund · dispute_refund · dispute_payout · …), recipient_role (a ROLE —\n provider · oracle · treasury · fee-collection · buyer — NEVER a wallet id; the sentinel \"unknown\" marks a\n leg type the backend does not map yet — logged loudly on their side, never money to the platform), amount, status, txid,\n anchor}, plus top-level `all_anchored` (true only when every leg's anchor is `anchored`). `status` is the LEDGER\n state of the leg (the money has moved once it reads completed); `txid` is written at BROADCAST, not at\n confirmation — so a leg can be settled with txid NULL (not broadcast yet — typically under a minute — OR its\n anchor dead-lettered) or carry a txid not yet on chain. A null txid on a fresh read is NOT a missing or failed\n leg: read `anchor`, the state to act on — queued | confirming | confirmed → poll (~30 s); anchored → verify the\n leg's txid on chain yourself (e.g. the `verify_proof` tool with the txid) — you don't have to trust us;\n failed | cancelled → the ledger leg settled but its anchor dead-lettered and will NOT reach the chain by\n itself (escalate); none → no anchor was attempted; unknown → a queue state the view does not recognise. This is the\n trade-WIDE view: `deposit_status` and a single transfer's status show only your own leg, not the payout\n or fees. Own trades only. Bearer or agent key required.\n CONTRACT SECTION — top-level `contract`, separate from `legs[]`: the on-chain escrow CONTRACT's own legs.\n They move no joules and have no recipient, so they never change `settled`, `leg_count` or `all_anchored`.\n `contract: null` = no escrow contract was recorded for this trade — a LEDGER-LANE trade (the default lane,\n `escrow_bsv_state` \"NO_CONTRACT\"; see `market_request`): normal, not a failure, and the settled `legs[]`\n are the record. Otherwise {version (the contract build), state (its latest state), closed (a FINAL leg\n exists: RELEASED · REFUNDED · SPLIT · TIMEOUT_REFUNDED · AUTO_REFUNDED), closed_on_chain (that final leg\n is anchored), closing_txid, legs[{state, txid, anchor (anchored · confirming · unknown), final}]}. An\n administrative closure is not a final leg, so it reads closed=false. `verify_proof` with the match_id\n reports the same trade's contract release as `release_anchor_status` (ledger_lane on a ledger-lane trade).",
"inputSchema": {
"properties": {
"match_id": {
"title": "Match Id",
"type": "string"
}
},
"required": [
"match_id"
],
"title": "trade_settlementArguments",
"type": "object"
},
"name": "trade_settlement",
"outputSchema": {
"additionalProperties": true,
"description": "trade_settlement — relayed verbatim from GET /api/v1/wallet/trade/{match_id}/settlement.",
"properties": {
"all_anchored": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true only when every leg's anchor is 'anchored'",
"title": "All Anchored"
},
"contract": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "the escrow CONTRACT's own chain legs {version, state, closed, closed_on_chain, closing_txid, legs[]}; null = no escrow contract was recorded (a ledger-lane trade)",
"title": "Contract"
},
"leg_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Leg Count"
},
"legs": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Legs"
},
"match_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Match Id"
},
"settled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Settled"
},
"your_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Your Role"
}
},
"title": "TradeSettlementOut",
"type": "object"
}
},
{
"description": "The latest hourly PUBLIC transparency attestation (GET /transparency/latest — no auth): a Merkle\n root over every wallet balance, the verified total supply, a transaction attestation, the state root,\n and the Bridge Ledger root, plus the BSV transaction that anchors the batch. ANCHORING IS BATCHED,\n NEVER IMMEDIATE: five attestations are anchored per OP_RETURN transaction, roughly every five hours.\n So the newest attestation's top-level `bsv_txid` legitimately reads the string \"pending\" for up to\n about five hours after its `timestamp` — that is the normal in-flight state, NOT \"unanchored\" and NOT\n an error. `last_anchored` names the most recent attestation whose batch IS on chain and carries a real\n 64-hex `bsv_txid` (with its merkle_root/bridge_root) you can open on a block explorer; `anchoring`\n restates the cadence. Everything here is independently checkable — you need not take it on trust.",
"inputSchema": {
"properties": {},
"title": "transparency_latestArguments",
"type": "object"
},
"name": "transparency_latest",
"outputSchema": {
"additionalProperties": true,
"description": "transparency_latest — hourly public attestation.",
"properties": {
"algorithm_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Algorithm Version"
},
"anchoring": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Anchoring"
},
"bridge_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Bridge Root"
},
"bridge_rows": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Bridge Rows"
},
"bsv_txid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "may read \"pending\" for ~5h — in-flight, NOT unanchored",
"title": "Bsv Txid"
},
"fees": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Fees"
},
"last_anchored": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "newest attestation actually on chain",
"title": "Last Anchored"
},
"merkle_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Merkle Root"
},
"settlement_leaves": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Settlement Leaves"
},
"settlement_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Settlement Root"
},
"state_root": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "State Root"
},
"supply_verified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Supply Verified"
},
"timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Timestamp"
},
"total_supply": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Supply"
},
"tx_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Tx Count"
},
"volume": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Volume"
},
"wallet_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Wallet Count"
}
},
"title": "TransparencyOut",
"type": "object"
}
},
{
"description": "Look up one identifier (chunk_id, proof_id, match_id, transfer id, or a BSV txid) in ENYAL's\n public verify lookup — no auth. The backend's body is returned UNCHANGED; read these fields, in this\n order, and claim nothing stronger than they say:\n - `found:true` = at least one of our systems holds a record for the id. For a chunk, proof or transfer\n UUID (a DATABASE record; a MATCH is different — see the marketplace-match bullet below):\n `anchor_status` ∈ {anchored | pending | unanchored} with `bsv_tx_id` — \"anchored\" means recorded as\n anchored; the chain is NOT checked on this path; `merkle_proof`/`merkle_root` are present only where\n the archive stores them. To check the chain, look up the returned `bsv_tx_id`.\n - For a bare txid (not a match): `chain_status` (confirmed | mempool | not_on_chain | unchecked) and\n `chain_confirmed` — this 4-value set is the WhatsOnChain status of one transaction and is distinct\n from a match's `release_anchor_status` enum below; do not conflate the two.\n Only `chain_confirmed:true` is a verified anchor. `mempool` can still be evicted.\n `found:false, recorded:true, chain_status:\"not_on_chain\"` = we recorded it but the network does not\n have it — a PHANTOM, not an anchor. Coverage (ENYAL as it runs, 2026-09-03): ENYAL's archive,\n RAREEAI escrow legs (fund/deliver/oracle/release/dispute/resolve/refund) + reputation, JoulePAI\n transfers + settlement queue; RAREEAI provider-REGISTRATION anchors are outside it.\n - `degraded:true` (+ `unavailable_sources`) = a source could not be checked; the result is\n INCONCLUSIVE, not an absence. Only `found:false, degraded:false` is a clean not-found.\n - For a RAREEAI marketplace match the body carries TWO INDEPENDENT on-chain claims — read both, collapse\n neither: `ledger_payout_anchor` (the joule movement that settled the trade — provider payout or buyer\n refund — with its own `txid`/`block_height`/`status`; this is the anchor a customer checks today, and it\n nests a batched `settlement_proof` leaf) and `escrow_contract_release_anchor` (the sCrypt escrow\n contract's terminal leg — its confirmed transaction id is `settlement_tx`, surfaced flat as\n `release_anchor_status`). `release_anchor_status` is an ENUM in the escrow lane's own vocabulary — read\n the value AND its `note`, never reduce it to anchored/not-anchored: confirmed | pending | unreachable |\n unanchored_open | closed_unanchored | fund_never_anchored | pre_contract | test_resolved | in_progress |\n ledger_lane. Only `confirmed` is a chain-confirmed contract release; `pending`/`unreachable` mean a\n release txid EXISTS but the chain has not confirmed it yet (`pending`) or WhatsOnChain could not be\n reached (`unreachable`) — retry, do not read them as unanchored. Every OTHER value explains why there\n is no contract txid at all — a ledger-lane, closed-unanchored, fund-never-anchored, pre-contract,\n test-resolved or in-progress trade is settled by the joule movement in `ledger_payout_anchor`, NOT by\n a missing anchor.\n Bridge-Ledger (contribution/fee) events are not in THIS ENYAL lookup, but they ARE anchored — batched\n into the hourly transparency attestation (bridge_root; five attestations per OP_RETURN transaction,\n roughly every five hours), and checkable with the `bridge_proof` tool (newest rows read anchoring\n \"pending\" until their batch is broadcast, then carry the batch txid). Graph edges are not verifiable\n here. This tool never decides — it relays ENYAL's verdict fields; a proof-ref it does not return\n does not exist as far as this lookup can see.",
"inputSchema": {
"properties": {
"identifier": {
"title": "Identifier",
"type": "string"
}
},
"required": [
"identifier"
],
"title": "verify_proofArguments",
"type": "object"
},
"name": "verify_proof",
"outputSchema": {
"additionalProperties": true,
"description": "verify_proof — the ENVELOPE only. `results` is an OPAQUE list and must stay that way: every\nper-record verdict field lives inside it, including `release_anchor_status` (11 values) and the\ntwo independent anchors (ledger_payout_anchor, escrow_contract_release_anchor). Modelling the\ninner records would risk collapsing or refusing an enum value, which is precisely the false\ncertainty this tool exists to prevent. Read the envelope for reachability, the records for verdicts.",
"properties": {
"chain_confirmed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "only true is a verified anchor",
"title": "Chain Confirmed"
},
"chain_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "bare-txid lookups: confirmed|mempool|not_on_chain|unchecked",
"title": "Chain Status"
},
"count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Count"
},
"degraded": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true = INCONCLUSIVE, never an absence",
"title": "Degraded"
},
"found": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "a record exists in at least one source",
"title": "Found"
},
"identifier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Identifier"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
},
"recorded": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "we hold it even if the chain does not",
"title": "Recorded"
},
"results": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "per-record verdicts, passed through untouched",
"title": "Results"
},
"unavailable_sources": {
"anyOf": [
{},
{
"type": "null"
}
],
"default": null,
"title": "Unavailable Sources"
}
},
"title": "VerifyOut",
"type": "object"
}
},
{
"description": "Direct wallet-to-wallet transfer (POST /wallet/transfer). Requires wallet:transfer scope. WHO CAN\n SEND (the backend as it runs, 2026-09-03): a verified human wallet to any wallet; an AGENT-class\n wallet (agent_customer / agent_citizen) ONLY to a REGISTERED destination — either a pending service\n registration matching {from, to, amount} (a quoted trade or metered charge; pass its registration_id)\n or the agent's own owner-of-record wallet (a wallet of the same ENYAL account). Any other destination\n is refused 403 (\"Agent wallets cannot transfer to arbitrary destinations…\"), relayed verbatim — do NOT\n retry with another destination. Also refused 403: a settlement-shaped `idempotency_key`\n (`release|refund|dispute_release|dispute_split:<match_id>:…`) unless the caller is the marketplace\n service — those keys belong to escrow settlement legs; never mint one, use a fresh opaque key. LIMITS ARE LIVE CONFIG, NOT CONSTANTS: the per-transfer and per-day\n caps for agent classes are read by the backend on every call from JoulePAI's GET\n /api/v1/programme/config → wallet_transfer_limits[<wallet_class>] (response carries version +\n config_md5) and change WITHOUT a deploy — read that route before planning a transfer and never plan\n against a remembered number; verified-human caps are on the JoulePAI docs. A transfer fee is charged\n to the sender (rate per the JoulePAI docs). A 202 acceptance carries a `bridge` block (units_earned,\n stream, your_share_bps, standing, config_md5) — keep it. Ineligible callers get the backend's real\n 403/402/422 verbatim. Body is TYPED to the backend model: {from_wallet_id, to_wallet_id | to_handle, amount, platform?,\n note?, idempotency_key?, privacy_mode?, include_proof?, registration_id?} — any other field is refused here.",
"inputSchema": {
"$defs": {
"TransferBody": {
"additionalProperties": false,
"properties": {
"amount": {
"exclusiveMinimum": 0,
"title": "Amount",
"type": "integer"
},
"from_wallet_id": {
"description": "sender wallet UUID (must be yours)",
"title": "From Wallet Id",
"type": "string"
},
"idempotency_key": {
"anyOf": [
{
"maxLength": 128,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Idempotency Key"
},
"include_proof": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Include Proof"
},
"note": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
},
"platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Platform"
},
"privacy_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Privacy Mode"
},
"registration_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "pending service registration id for an agent-class quoted transfer",
"title": "Registration Id"
},
"to_handle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Handle"
},
"to_wallet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Wallet Id"
}
},
"required": [
"from_wallet_id",
"amount"
],
"title": "TransferBody",
"type": "object"
}
},
"properties": {
"body": {
"$ref": "#/$defs/TransferBody"
}
},
"required": [
"body"
],
"title": "wallet_transferArguments",
"type": "object"
},
"name": "wallet_transfer",
"outputSchema": {
"additionalProperties": true,
"title": "wallet_transferDictOutput",
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:0a460c1b225ec77b1fbe908e8699f997ae5fe1c06e09b261d1952399a21e6eb2 | sha256sum