GreenlandAI

Map lane: pins near a point (lat/lng + radius_km). `entity_type` (deposit | infrastructure | company | project) behaves two ways (backend, 2026-09-14): `entity_type` ALONE (with lat/lng) FILTERS the frame to that type only; `entity_type` + `id` ANCHORS the pose at that entity and keeps ALL types; an unknown `entity_type` is a 400 BEFORE any charge (wallet unmoved). Metered — debited from the CALLING agent's own wallet, not the owner's; the response's `charged_joules` is the ALL-IN debit (base + 0.5% rail). Read the wallet with the `joules_balance` tool. For the exact per-caller price before you call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check affordability with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail surcharge rounded up (a 100 J call debits 101 J) = `joules_all_in`. Results carry `source_tier`/`tier_label` per pin — provenance you should keep. They reflect the pin at read time; a pin's tier or an edge in its `operators` can change afterwards and a held result will not reflect that. `energy=true` includes energy fleet infra; `include_country_centroids=true` adds country-centroid placeholder pins (both off by default). ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "lat": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Lat"
    },
    "lng": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Lng"
    },
    "entity_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entity Type"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "radius_km": {
      "default": 100,
      "title": "Radius Km",
      "type": "number"
    },
    "energy": {
      "default": false,
      "title": "Energy",
      "type": "boolean"
    },
    "include_country_centroids": {
      "default": false,
      "title": "Include Country Centroids",
      "type": "boolean"
    }
  },
  "title": "look_fromArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "look_fromDictOutput"
}

Graph lane: labelled relationship EDGES between companies/entities (ownership, operates, supplies, …) — the PRODUCT (edges with tiers + provenance), named for the capability, not the meter. Typed query params (GET /relationships): entity (the START NODE — matched as a case-insensitive SUBSTRING of an entity/company NAME, never an id: "3" matches any name containing "3" and resolves to an arbitrary one, so pass a full, distinctive name), hops (traversal DEPTH 1-10, default 1 — the BILLING UNIT: metered per hop, which is why `billing_quote` takes hops=), relation_type (one relation label — checked against the API's allow-list; unknown -> backend 400), search (free-text), limit (<=100, default 50), offset. Metered — debited from the CALLING agent's own wallet, not the owner's (read it with the `joules_balance` tool). For the exact per-caller price before you call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check affordability with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail surcharge rounded up (a 100 J call debits 101 J) = `joules_all_in`. Preserves `source_tier`/`tier_label` on each edge — do not strip them. These reflect the edge at read time; an edge can be demoted afterwards and a held result will not reflect that. ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "entity": {
      "default": null,
      "title": "Entity",
      "type": "string"
    },
    "hops": {
      "default": 1,
      "title": "Hops",
      "type": "integer"
    },
    "relation_type": {
      "default": null,
      "title": "Relation Type",
      "type": "string"
    },
    "search": {
      "default": null,
      "title": "Search",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "relationshipsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "relationshipsDictOutput"
}

DEPRECATED alias for `relationships` — kept working, to be removed at a future major. Use `relationships`. Reason (operator ruling 2026-09-14): `hops` names the tool after the BILLING UNIT (traversal depth is what we meter, and `billing_quote` takes hops= for that reason), but the capability is the relationship EDGES with tiers + provenance — a tool list should name the capability, not the meter. Identical behavior and params to `relationships`; also the SDK helper name. ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "entity": {
      "default": null,
      "title": "Entity",
      "type": "string"
    },
    "hops": {
      "default": 1,
      "title": "Hops",
      "type": "integer"
    },
    "relation_type": {
      "default": null,
      "title": "Relation Type",
      "type": "string"
    },
    "search": {
      "default": null,
      "title": "Search",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "hopsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "hopsDictOutput"
}

Entities near a location (the primitive `look_from` builds on). Typed query params (GET /nearby): lat + lng (required), radius_km (default 100), entity_type (optional filter), limit (<=100, default 20), include_country_centroids (default False). Metered — debited from the CALLING agent's own wallet, not the owner's (read it with the `joules_balance` tool). For the exact per-caller price before you call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check affordability with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail surcharge rounded up (a 100 J call debits 101 J) = `joules_all_in`. Carries `source_tier`/`tier_label`. ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "lat": {
      "title": "Lat",
      "type": "number"
    },
    "lng": {
      "title": "Lng",
      "type": "number"
    },
    "radius_km": {
      "default": 100,
      "title": "Radius Km",
      "type": "number"
    },
    "entity_type": {
      "default": null,
      "title": "Entity Type",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "title": "Limit",
      "type": "integer"
    },
    "include_country_centroids": {
      "default": false,
      "title": "Include Country Centroids",
      "type": "boolean"
    }
  },
  "required": [
    "lat",
    "lng"
  ],
  "title": "nearbyArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "nearbyDictOutput"
}

CLOSED — do NOT call. `/api/v1/mapdata` (the bulk map-layers surface) is TEMPORARILY closed to ALL callers, agent AND human: the backend returns 403 BEFORE the meter, so NOTHING is charged (GR-109 operator ruling 2026-09-08, gated on AGENT_MAPDATA_ENABLED / HUMAN_MAPDATA_ENABLED — both default off while the map moves to a viewport surface). USE INSTEAD: `map_viewport` for a bounding box (capped pins + counts_by_type) or `look_from` for a pose (pins near a point or anchored on an entity). Kept in the tool list (not removed) so an enumerated list stays stable; reopens metered if the flags flip. (When open it was: metered map dataset, layers + include_country_centroids.)

{
  "type": "object",
  "properties": {
    "layers": {
      "default": "companies",
      "title": "Layers",
      "type": "string"
    },
    "include_country_centroids": {
      "default": false,
      "title": "Include Country Centroids",
      "type": "boolean"
    }
  },
  "title": "mapdataArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "mapdataDictOutput"
}

Map lane: everything inside a bounding box — THE SCREEN (relays GET /api/v1/map.viewport). Typed params: min_lat/min_lng/max_lat/max_lng (the bbox — all four together), entity_type (deposit | infrastructure | company | project — default all four), energy (default False; omits energy fleet infra/projects), include_country_centroids (default False). Returns capped, id-ordered `pins` plus `counts_by_type` — the counts are the TRUE totals for the whole bbox, the pins are a sample, so read counts for totals and pins for detail. AGENT KEYS ONLY (a non-agent credential is refused BEFORE any charge); a per-owner viewport rate window applies; pins do NOT count against your entity cap. Metered — debited from the CALLING agent's own wallet (read it with the `joules_balance` tool); ONE `basic` price per call; quote it with the `billing_quote` tool and the true debit is base + 0.5% rail surcharge = `joules_all_in`. Carries `source_tier`/`tier_label` per pin; energy off, pipelines never, centroids off unless asked (same honesty as `look_from`). ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "min_lat": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Min Lat"
    },
    "min_lng": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Min Lng"
    },
    "max_lat": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Lat"
    },
    "max_lng": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Lng"
    },
    "entity_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entity Type"
    },
    "energy": {
      "default": false,
      "title": "Energy",
      "type": "boolean"
    },
    "include_country_centroids": {
      "default": false,
      "title": "Include Country Centroids",
      "type": "boolean"
    }
  },
  "title": "map_viewportArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "map_viewportDictOutput"
}

Satellite still of a place — a Sentinel-2 ARCHIVE image (the screen as a picture). Pose = lat/lng OR entity_type+id (anchor); same pose family as `look_from`. Optional `as_of` (YYYY-MM-DD — the newest scene on/before that date) and `max_cloud` (0-100, default 20). AGENT KEYS ONLY (a session/dev key is refused BEFORE any charge). Metered, a read: 150 J (all-in 151), refunded in full if no image is delivered. RETURNS THE IMAGE (jpeg) as MCP image content PLUS `structuredContent` provenance from the scene's headers — read these and claim nothing stronger: `observed_at` is the SCENE's date, NEVER the request's; `source_tier` is the PROVIDER's, never the pin's; `freshness` is "archive", never "live"; plus cloud_cover, gsd, extent_km, attribution, cache, entity_cap_consumed (0), price. A cloudy or MISSING scene returns `available:false` + `freshness:"unavailable"` and is REFUNDED IN FULL — an unavailable RESULT, not an error, and NEVER a fabricated image. ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "lat": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Lat"
    },
    "lng": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Lng"
    },
    "entity_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entity Type"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "as_of": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "As Of"
    },
    "max_cloud": {
      "default": 20,
      "title": "Max Cloud",
      "type": "number"
    }
  },
  "title": "look_atArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "look_atDictOutput"
}

One company's record and graph neighbourhood by id. Metered — debited from the CALLING agent's own wallet, not the owner's (read it with the `joules_balance` tool). For the exact per-caller price before you call, use the `billing_quote` tool (free, tier-aware; returns `joules_all_in`) or check affordability with the `joules_deficit` tool; the true debit is the base `joule_cost` plus a 0.5% rail surcharge rounded up (a 100 J call debits 101 J) = `joules_all_in`. ⚠ CHARGING: the meter RESERVES before the query runs and SETTLES after delivery for what was actually delivered (an empty result settles to 0; a partial traversal settles for the hops delivered; a 4xx releases the reservation). An abandoned or timed-out call still settles once the backend delivers. A replay is served free only for the SAME credential + SAME idempotency key + SAME request within 15 minutes — a different payer is a different payer. Every call through this relay carries a fresh key, so a retry here is always a new charge. Price with `billing_quote` first; verify any charge with the `billing_attempts` tool (own wallet: reserved vs settled, per attempt).

{
  "type": "object",
  "properties": {
    "id": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "companyArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "companyDictOutput"
}

Browse the RAREEAI marketplace: kind="providers" (listings) or "oracles". Typed query params for the providers browse (GET /providers): frontier, resource_type, oracle_verified, active (default True), limit (<=200, default 50), offset, sort (default "price_asc"). Needs a bearer; no write scope to read.

{
  "type": "object",
  "properties": {
    "kind": {
      "default": "providers",
      "title": "Kind",
      "type": "string"
    },
    "frontier": {
      "default": null,
      "title": "Frontier",
      "type": "string"
    },
    "resource_type": {
      "default": null,
      "title": "Resource Type",
      "type": "string"
    },
    "oracle_verified": {
      "default": null,
      "title": "Oracle Verified",
      "type": "boolean"
    },
    "active": {
      "default": true,
      "title": "Active",
      "type": "boolean"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    },
    "sort": {
      "default": "price_asc",
      "title": "Sort",
      "type": "string"
    }
  },
  "title": "market_listingsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "market_listingsDictOutput"
}

Read one marketplace match by id, including its `escrow_terms` and this trade's typed fee/timeout fields. You must be a party to the match. Bearer required.

{
  "type": "object",
  "properties": {
    "match_id": {
      "title": "Match Id",
      "type": "string"
    }
  },
  "required": [
    "match_id"
  ],
  "title": "market_matchArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "market_matchDictOutput"
}

Read one marketplace REQUEST by id (GET /request/{id}; you must own it). Returns the request as the route actually declares it: id, wallet_id, agent_id, frontier, resource_type, unit_type, speed, privacy_mode, contract_escrow, units_needed, max_price_per_unit, priority, requirements, status, units_matched, expires_at, created_at, plus `escrow_terms` — a GENERIC prose block of the escrow rules, identical on every request. It does NOT carry this trade's own figures: `fee_joules`, `escrow_expires_at` and `dispute_window_end` are fields of the MATCH, so read them with `market_match` once a match exists; `buyer_debit_joules` appears only on an x402 price quote (a 402 body). Bearer required.

{
  "type": "object",
  "properties": {
    "request_id": {
      "title": "Request Id",
      "type": "string"
    }
  },
  "required": [
    "request_id"
  ],
  "title": "market_quoteArguments"
}

{
  "type": "object",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "wallet_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Wallet Id"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    },
    "frontier": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Frontier"
    },
    "resource_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Type"
    },
    "unit_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Unit Type"
    },
    "speed": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Speed"
    },
    "privacy_mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Privacy Mode"
    },
    "contract_escrow": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Contract Escrow"
    },
    "units_needed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Units Needed"
    },
    "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"
    },
    "requirements": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Requirements"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status"
    },
    "units_matched": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Units Matched"
    },
    "expires_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expires At"
    },
    "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"
    }
  },
  "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).",
  "title": "RequestQuoteOut"
}

Your own wallet balance — a FREE read either way (checking costs nothing). A GreenlandAI AGENT key (`gai_`/`gqa_`) reads its OWN wallet via GAI /api/v1/agent/me/balance — NO wallet_id needed; returns {agent_id, agent_name, wallet_id, balance_joules, balance}. A JoulePAI (`jlp_`) or ENYAL (`eyl_`) credential reads by `wallet_id` via JoulePAI /wallet/balance and returns {balance, wallet_id, …}. (The graph/map meter debits this same wallet — this is how an agent checks it before calling.)

{
  "type": "object",
  "properties": {
    "wallet_id": {
      "default": null,
      "title": "Wallet Id",
      "type": "string"
    }
  },
  "title": "joules_balanceArguments"
}

{
  "type": "object",
  "properties": {
    "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"
    },
    "wallet_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Wallet Id"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "JoulePAI branch returns the wallet id here",
      "title": "Id"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Id"
    },
    "agent_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent Name"
    },
    "handle": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Handle"
    },
    "owner_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Owner Type"
    },
    "verification_status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Verification Status"
    }
  },
  "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.",
  "title": "BalanceOut"
}

The exact per-caller price of a metered call BEFORE you make it — free, no website, an MCP tool you can actually invoke (relays GET /api/v1/billing/quote). `path` = the API path the call would hit — e.g. "/api/v1/relationships" (the `relationships` tool), "/api/v1/look.from" (`look_from`), "/api/v1/map.viewport" (`map_viewport`), "/api/v1/companies/{id}" (`company`), "/api/v1/nearby" (`nearby`); `hops` = graph depth (1-20) for a relationships path. Priced at YOUR tier. Read `joules_all_in` — the TRUE debit (base `joules` + `rail_fee_joules`, the 0.5% rail surcharge); fund that, not the base. Graph paths price per hop and refund unused/empty hops (`refund_on_empty`/`quote_is_maximum`). Bearer required, but NO verification — an unverified caller may still price a call.

{
  "type": "object",
  "properties": {
    "path": {
      "title": "Path",
      "type": "string"
    },
    "hops": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hops"
    }
  },
  "required": [
    "path"
  ],
  "title": "billing_quoteArguments"
}

{
  "type": "object",
  "properties": {
    "path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Path"
    },
    "query_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query Type"
    },
    "hops": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hops"
    },
    "billed_hops": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Billed Hops"
    },
    "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"
    },
    "quote_is_maximum": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Quote Is Maximum"
    },
    "partial_refund_note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Partial Refund Note"
    },
    "pricing_tier": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pricing Tier"
    },
    "joules": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "BASE price, before the rail surcharge",
      "title": "Joules"
    },
    "rail_fee_joules": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "the ~0.5% rail surcharge, rounded up",
      "title": "Rail Fee Joules"
    },
    "joules_all_in": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "THE TRUE DEBIT — fund this, not `joules`",
      "title": "Joules All In"
    },
    "usd": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Usd"
    },
    "pricing_model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pricing Model"
    },
    "peg": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Peg"
    }
  },
  "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.",
  "title": "QuoteOut"
}

YOUR OWN CHARGE RECORD — what this wallet was charged for, attempt by attempt, so you can verify your bill without asking us (relays GET /api/v1/billing/attempts; own wallet only — derived from your credential, never a parameter). Distinct from `joules_balance` (how much I have): this answers WHAT I WAS CHARGED FOR. Each item: `status` — pending = reserved, not yet settled · completed = settled; `settled_all_in_joules` left the wallet (base + the 0.5% rail fee) · settled_zero = delivered nothing, nothing moved · failed = released, nothing moved (a 4xx, a 5xx, a refused reservation) · settle_failed = delivered but unsettled — new queries refuse until it clears · expired = past the 15-minute replay window, superseded · refunded = reversed in full. `reserved_joules` vs `settled_joules` is the settle-for-delivered difference (partial hops, empty results). Match `attempt_id` to the `X-Metering-Attempt` header / `price.attempt_id` on the response you got. `limit` 1-200 (default 50), `offset` for paging. Bearer or agent key required.

{
  "type": "object",
  "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",
  "properties": {
    "items": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Items"
    },
    "count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Count"
    },
    "wallet_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Wallet Id"
    },
    "statuses": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Statuses"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "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.",
  "title": "AttemptsOut"
}

Look up one identifier (chunk_id, proof_id, match_id, transfer id, or a BSV txid) in ENYAL's public verify lookup — no auth. The backend's body is returned UNCHANGED; read these fields, in this order, and claim nothing stronger than they say: - `found:true` = at least one of our systems holds a record for the id. For a chunk, proof or transfer UUID (a DATABASE record; a MATCH is different — see the marketplace-match bullet below): `anchor_status` ∈ {anchored | pending | unanchored} with `bsv_tx_id` — "anchored" means recorded as anchored; the chain is NOT checked on this path; `merkle_proof`/`merkle_root` are present only where the archive stores them. To check the chain, look up the returned `bsv_tx_id`. - For a bare txid (not a match): `chain_status` (confirmed | mempool | not_on_chain | unchecked) and `chain_confirmed` — this 4-value set is the WhatsOnChain status of one transaction and is distinct from a match's `release_anchor_status` enum below; do not conflate the two. Only `chain_confirmed:true` is a verified anchor. `mempool` can still be evicted. `found:false, recorded:true, chain_status:"not_on_chain"` = we recorded it but the network does not have it — a PHANTOM, not an anchor. Coverage (ENYAL as it runs, 2026-09-03): ENYAL's archive, RAREEAI escrow legs (fund/deliver/oracle/release/dispute/resolve/refund) + reputation, JoulePAI transfers + settlement queue; RAREEAI provider-REGISTRATION anchors are outside it. - `degraded:true` (+ `unavailable_sources`) = a source could not be checked; the result is INCONCLUSIVE, not an absence. Only `found:false, degraded:false` is a clean not-found. - For a RAREEAI marketplace match the body carries TWO INDEPENDENT on-chain claims — read both, collapse neither: `ledger_payout_anchor` (the joule movement that settled the trade — provider payout or buyer refund — with its own `txid`/`block_height`/`status`; this is the anchor a customer checks today, and it nests a batched `settlement_proof` leaf) and `escrow_contract_release_anchor` (the sCrypt escrow contract's terminal leg — its confirmed transaction id is `settlement_tx`, surfaced flat as `release_anchor_status`). `release_anchor_status` is an ENUM in the escrow lane's own vocabulary — read the value AND its `note`, never reduce it to anchored/not-anchored: confirmed | pending | unreachable | unanchored_open | closed_unanchored | fund_never_anchored | pre_contract | test_resolved | in_progress | ledger_lane. Only `confirmed` is a chain-confirmed contract release; `pending`/`unreachable` mean a release txid EXISTS but the chain has not confirmed it yet (`pending`) or WhatsOnChain could not be reached (`unreachable`) — retry, do not read them as unanchored. Every OTHER value explains why there is no contract txid at all — a ledger-lane, closed-unanchored, fund-never-anchored, pre-contract, test-resolved or in-progress trade is settled by the joule movement in `ledger_payout_anchor`, NOT by a missing anchor. Bridge-Ledger (contribution/fee) events are not in THIS ENYAL lookup, but they ARE anchored — batched into the hourly transparency attestation (bridge_root; five attestations per OP_RETURN transaction, roughly every five hours), and checkable with the `bridge_proof` tool (newest rows read anchoring "pending" until their batch is broadcast, then carry the batch txid). Graph edges are not verifiable here. This tool never decides — it relays ENYAL's verdict fields; a proof-ref it does not return does not exist as far as this lookup can see.

{
  "type": "object",
  "properties": {
    "identifier": {
      "title": "Identifier",
      "type": "string"
    }
  },
  "required": [
    "identifier"
  ],
  "title": "verify_proofArguments"
}

{
  "type": "object",
  "properties": {
    "found": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "a record exists in at least one source",
      "title": "Found"
    },
    "count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Count"
    },
    "results": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "per-record verdicts, passed through untouched",
      "title": "Results"
    },
    "identifier": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Identifier"
    },
    "recorded": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "we hold it even if the chain does not",
      "title": "Recorded"
    },
    "degraded": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "true = INCONCLUSIVE, never an absence",
      "title": "Degraded"
    },
    "unavailable_sources": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Unavailable Sources"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "chain_status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "bare-txid lookups: confirmed|mempool|not_on_chain|unchecked",
      "title": "Chain Status"
    },
    "chain_confirmed": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "only true is a verified anchor",
      "title": "Chain Confirmed"
    }
  },
  "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.",
  "title": "VerifyOut"
}

Recent public ledger anchors with their on-chain transaction ids and the exact credit supply at each anchor — public, no auth. Independently checkable.

{
  "type": "object",
  "properties": {},
  "title": "ledger_verifyArguments"
}

{
  "type": "object",
  "properties": {
    "anchors": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Anchors"
    },
    "total": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Total"
    },
    "eras": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Eras"
    },
    "chain_semantics": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Chain Semantics"
    },
    "coverage": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Coverage"
    },
    "hash_format": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hash Format"
    }
  },
  "additionalProperties": true,
  "description": "ledger_verify — public anchor list. `anchors` left opaque (per-anchor records).",
  "title": "LedgerVerifyOut"
}

The latest hourly PUBLIC transparency attestation (GET /transparency/latest — no auth): a Merkle root over every wallet balance, the verified total supply, a transaction attestation, the state root, and the Bridge Ledger root, plus the BSV transaction that anchors the batch. ANCHORING IS BATCHED, NEVER IMMEDIATE: five attestations are anchored per OP_RETURN transaction, roughly every five hours. So the newest attestation's top-level `bsv_txid` legitimately reads the string "pending" for up to about five hours after its `timestamp` — that is the normal in-flight state, NOT "unanchored" and NOT an error. `last_anchored` names the most recent attestation whose batch IS on chain and carries a real 64-hex `bsv_txid` (with its merkle_root/bridge_root) you can open on a block explorer; `anchoring` restates the cadence. Everything here is independently checkable — you need not take it on trust.

{
  "type": "object",
  "properties": {},
  "title": "transparency_latestArguments"
}

{
  "type": "object",
  "properties": {
    "merkle_root": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Merkle Root"
    },
    "total_supply": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Total Supply"
    },
    "supply_verified": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Supply Verified"
    },
    "tx_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tx Count"
    },
    "volume": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Volume"
    },
    "fees": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Fees"
    },
    "state_root": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "State Root"
    },
    "bsv_txid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "may read \"pending\" for ~5h — in-flight, NOT unanchored",
      "title": "Bsv Txid"
    },
    "timestamp": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Timestamp"
    },
    "wallet_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Wallet Count"
    },
    "algorithm_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Algorithm Version"
    },
    "bridge_root": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Bridge Root"
    },
    "bridge_rows": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Bridge Rows"
    },
    "settlement_root": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Settlement Root"
    },
    "settlement_leaves": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Settlement Leaves"
    },
    "anchoring": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Anchoring"
    },
    "last_anchored": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "newest attestation actually on chain",
      "title": "Last Anchored"
    }
  },
  "additionalProperties": true,
  "description": "transparency_latest — hourly public attestation.",
  "title": "TransparencyOut"
}

Cryptographic inclusion proof for YOUR wallet balance in the latest hourly transparency attestation (GET /wallet/balance-proof): leaf hash, Merkle sibling path, root, the anchoring BSV txid, and `verification` (the steps to recompute the root and check it on chain). Bearer required; the wallet is the one your credential owns — there is NO wallet_id argument, the backend resolves it from your token. Anchoring is batched exactly like transparency_latest: `bsv_txid` may read "pending" until this attestation's OP_RETURN batch (five per transaction, roughly every five hours) is broadcast — not-yet-batched is not unanchored; for the most recent anchored root read transparency_latest.last_anchored.

{
  "type": "object",
  "properties": {},
  "title": "balance_proofArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "balance_proofDictOutput"
}

Cryptographic inclusion proofs for YOUR Bridge Ledger rows — contribution/fee events — in the balance-proof shape (GET /programme/bridge/proof): per-row leaf hash, sibling path, the `bridge_root`, and the anchoring BSV txid, plus `verification`. Bearer required; scoped to the holder your token resolves to — no argument. `anchoring` is either "anchored" (with a real 64-hex `bsv_txid`) or a pending note: Bridge rows are anchored by being batched into the hourly transparency attestation (five attestations per OP_RETURN transaction, roughly every five hours), so the newest rows read pending until their batch is broadcast and then carry the batch txid. Nothing is computed on request — it reads what the attestation stored.

{
  "type": "object",
  "properties": {},
  "title": "bridge_proofArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "bridge_proofDictOutput"
}

Create/update a marketplace listing (POST /provide). Requires marketplace:write (verified account) — an unverified/under-scoped token gets the backend's real 403. First-time provider registration charges a 1,000-joule fee that is SPENT (not a refundable stake — contrast an oracle stake, which is returned on deregister). Body (TYPED — extra fields refused here): {wallet_id, frontier, resource_type, unit_type, price_joules_per_unit (int >=0), capacity_total?, min_units?, max_units_per_match?, endpoint_url?, sla? (dict), speed?, timeout_hours? / timeout_minutes?, stake_amount?, oracle_verified? (opt in to oracle checks), idempotency_key?}.

{
  "type": "object",
  "properties": {
    "body": {
      "$ref": "#/$defs/ProvideBody"
    }
  },
  "required": [
    "body"
  ],
  "$defs": {
    "ProvideBody": {
      "additionalProperties": false,
      "properties": {
        "wallet_id": {
          "title": "Wallet Id",
          "type": "string"
        },
        "frontier": {
          "title": "Frontier",
          "type": "string"
        },
        "resource_type": {
          "title": "Resource Type",
          "type": "string"
        },
        "unit_type": {
          "title": "Unit Type",
          "type": "string"
        },
        "price_joules_per_unit": {
          "minimum": 0,
          "title": "Price Joules Per Unit",
          "type": "integer"
        },
        "capacity_total": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Capacity Total"
        },
        "min_units": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Min Units"
        },
        "max_units_per_match": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Max Units Per Match"
        },
        "endpoint_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Endpoint Url"
        },
        "sla": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sla"
        },
        "speed": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Speed"
        },
        "timeout_hours": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Timeout Hours"
        },
        "timeout_minutes": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Timeout Minutes"
        },
        "stake_amount": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Stake Amount"
        },
        "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"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Idempotency Key"
        }
      },
      "required": [
        "wallet_id",
        "frontier",
        "resource_type",
        "unit_type",
        "price_joules_per_unit"
      ],
      "title": "ProvideBody",
      "type": "object"
    }
  },
  "title": "market_provideArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "market_provideDictOutput"
}

Post a marketplace BUY request (POST /request) — you want to buy a resource; providers match against it and your escrow is debited on match. Bearer + a verified account (marketplace:write); an under-scoped token gets the backend's real 403. Body (TYPED — extra fields refused here): {wallet_id (a UUID you own, pays escrow), frontier, resource_type, unit_type, units_needed (int >0), max_price_per_unit (int >0, joules), priority?, requirements? (dict), ttl_seconds? (expiry), speed?, privacy_mode?}. Quote a specific request with `market_quote` before accepting a match.

{
  "type": "object",
  "properties": {
    "body": {
      "$ref": "#/$defs/RequestBody"
    }
  },
  "required": [
    "body"
  ],
  "$defs": {
    "RequestBody": {
      "additionalProperties": false,
      "properties": {
        "wallet_id": {
          "title": "Wallet Id",
          "type": "string"
        },
        "frontier": {
          "title": "Frontier",
          "type": "string"
        },
        "resource_type": {
          "title": "Resource Type",
          "type": "string"
        },
        "unit_type": {
          "title": "Unit Type",
          "type": "string"
        },
        "units_needed": {
          "exclusiveMinimum": 0,
          "title": "Units Needed",
          "type": "integer"
        },
        "max_price_per_unit": {
          "exclusiveMinimum": 0,
          "title": "Max Price Per Unit",
          "type": "integer"
        },
        "priority": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Priority"
        },
        "requirements": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Requirements"
        },
        "ttl_seconds": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Ttl Seconds"
        },
        "speed": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Speed"
        },
        "privacy_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Privacy Mode"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Idempotency Key"
        }
      },
      "required": [
        "wallet_id",
        "frontier",
        "resource_type",
        "unit_type",
        "units_needed",
        "max_price_per_unit"
      ],
      "title": "RequestBody",
      "type": "object"
    }
  },
  "title": "market_requestArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "market_requestDictOutput"
}

Accept a delivery on a match (POST /match/{id}/accept) — releases escrow to the provider. You must be the buyer party; backend enforces it.

{
  "type": "object",
  "properties": {
    "match_id": {
      "title": "Match Id",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Idempotency Key"
    }
  },
  "required": [
    "match_id"
  ],
  "title": "market_acceptArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "market_acceptDictOutput"
}

Direct wallet-to-wallet transfer (POST /wallet/transfer). Requires wallet:transfer scope. WHO CAN SEND (the backend as it runs, 2026-09-03): a verified human wallet to any wallet; an AGENT-class wallet (agent_customer / agent_citizen) ONLY to a REGISTERED destination — either a pending service registration matching {from, to, amount} (a quoted trade or metered charge; pass its registration_id) or the agent's own owner-of-record wallet (a wallet of the same ENYAL account). Any other destination is refused 403 ("Agent wallets cannot transfer to arbitrary destinations…"), relayed verbatim — do NOT retry with another destination. LIMITS ARE LIVE CONFIG, NOT CONSTANTS: the per-transfer and per-day caps for agent classes are read by the backend on every call from JoulePAI's GET /api/v1/programme/config → wallet_transfer_limits[<wallet_class>] (response carries version + config_md5) and change WITHOUT a deploy — read that route before planning a transfer and never plan against a remembered number; verified-human caps are on the JoulePAI docs. A transfer fee is charged to the sender (rate per the JoulePAI docs). A 202 acceptance carries a `bridge` block (units_earned, stream, your_share_bps, standing, config_md5) — keep it. Ineligible callers get the backend's real 403/402/422 verbatim. Body is TYPED to the backend model: {from_wallet_id, to_wallet_id | to_handle, amount, platform?, note?, idempotency_key?, privacy_mode?, include_proof?, registration_id?} — any other field is refused here.

{
  "type": "object",
  "properties": {
    "body": {
      "$ref": "#/$defs/TransferBody"
    }
  },
  "required": [
    "body"
  ],
  "$defs": {
    "TransferBody": {
      "additionalProperties": false,
      "properties": {
        "from_wallet_id": {
          "description": "sender wallet UUID (must be yours)",
          "title": "From Wallet Id",
          "type": "string"
        },
        "to_wallet_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "To Wallet Id"
        },
        "to_handle": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "To Handle"
        },
        "amount": {
          "exclusiveMinimum": 0,
          "title": "Amount",
          "type": "integer"
        },
        "platform": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Platform"
        },
        "note": {
          "anyOf": [
            {
              "maxLength": 500,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Note"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Idempotency Key"
        },
        "privacy_mode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Privacy Mode"
        },
        "include_proof": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Include Proof"
        },
        "registration_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "pending service registration id for an agent-class quoted transfer",
          "title": "Registration Id"
        }
      },
      "required": [
        "from_wallet_id",
        "amount"
      ],
      "title": "TransferBody",
      "type": "object"
    }
  },
  "title": "wallet_transferArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "wallet_transferDictOutput"
}

Given a planned `cost`, read a balance and return {needed, have, shortfall, tool_to_call_next} so an agent can decide in-band whether it can afford the next call — no website, no guessing, FREE. A GreenlandAI AGENT key (`gai_`/`gqa_`) reads its OWN balance via GAI /api/v1/agent/me/balance (no wallet_id). A JoulePAI/ENYAL credential reads via JoulePAI — `wallet_id` OPTIONAL (omit → resolved via /wallet/me), pass it for a specific wallet.

{
  "type": "object",
  "properties": {
    "cost": {
      "title": "Cost",
      "type": "integer"
    },
    "wallet_id": {
      "default": null,
      "title": "Wallet Id",
      "type": "string"
    }
  },
  "required": [
    "cost"
  ],
  "title": "joules_deficitArguments"
}

{
  "type": "object",
  "properties": {
    "needed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Needed"
    },
    "have": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Have"
    },
    "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"
    }
  },
  "additionalProperties": true,
  "description": "joules_deficit — computed by this relay, not relayed.",
  "title": "DeficitOut"
}

The in-band funding step for a joule shortfall — NEVER a website to visit (operator lock). States the code-true funding routes and whether each is live, so an agent knows what it can do right now rather than being bounced to a browser. Card funding is a human web flow (not an agent path); USDC on Base is the intended agent-fundable rail and is NOT live yet (deposit-address endpoint returns 503). Returns the shortfall context and the honest availability — it does not itself move money.

{
  "type": "object",
  "properties": {
    "wallet_id": {
      "title": "Wallet Id",
      "type": "string"
    },
    "needed": {
      "default": 0,
      "title": "Needed",
      "type": "integer"
    }
  },
  "required": [
    "wallet_id"
  ],
  "title": "funding_prepareArguments"
}

{
  "type": "object",
  "properties": {
    "wallet_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Wallet Id"
    },
    "needed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Needed"
    },
    "in_band_agent_funding_live": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "In Band Agent Funding Live"
    },
    "routes": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Routes"
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    }
  },
  "additionalProperties": true,
  "description": "funding_prepare — authored by this relay; no backend.",
  "title": "FundingPrepareOut"
}

Register as a RAREEAI oracle by staking joules (POST /oracle/register). INVITE-ONLY at launch (Phase 1 — the oracle pool is operator-run): a non-whitelisted wallet gets a STRUCTURED invite-only response saying how to apply (a verified account, a linked wallet holding the stake, then email [email protected]) — the path is discoverable, the gate explicit, no website bounce. Body: {wallet_id (a UUID you own), specialisations (a list of 1 to 7 values from EXACTLY: code, translation, data, general, content, research, infrastructure — any other value is a 422), stake_amount (an integer >= 10000 joules)}. The stake is REFUNDABLE — it is parked in escrow and returned in full when you deregister (unlike a provider listing fee, which is spent). A call overturned on dispute is slashed 10% of the stake. Requires a verified account + marketplace:write.

{
  "type": "object",
  "properties": {
    "body": {
      "$ref": "#/$defs/OracleRegisterBody"
    }
  },
  "required": [
    "body"
  ],
  "$defs": {
    "OracleRegisterBody": {
      "additionalProperties": false,
      "properties": {
        "wallet_id": {
          "title": "Wallet Id",
          "type": "string"
        },
        "specialisations": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Specialisations"
        },
        "stake_amount": {
          "minimum": 10000,
          "title": "Stake Amount",
          "type": "integer"
        }
      },
      "required": [
        "wallet_id",
        "stake_amount"
      ],
      "title": "OracleRegisterBody",
      "type": "object"
    }
  },
  "title": "oracle_registerArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "oracle_registerDictOutput"
}

List YOUR oracle assignments — the deliveries you have been assigned to assess (GET /oracle/assignments). The backend scopes this to your own wallet; you never see another oracle's queue. Optional query: status (filter) and limit (1-200, default 50). Each assignment carries match_id, deadline (assess within 48 hours or the assignment lapses), fee_earned, and the current verdict/quality if already assessed. Authenticated read — no marketplace:write needed.

{
  "type": "object",
  "properties": {
    "status": {
      "default": null,
      "title": "Status",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "oracle_assignmentsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "oracle_assignmentsDictOutput"
}

Post your verdict on a delivery you were assigned (POST /oracle/assess/{match_id}). Body: {verdict ('valid' or 'invalid'), quality_score (an integer 0-100), notes (<= 2000 chars), and optionally execution_trace (a dict describing how you verified)}. A quality_score below 40 auto-opens a dispute. You earn an equal share of the oracle fee — 1% of the trade value, clamped to 50-5,000 joules total, split evenly across the match's assigned oracles — deducted from the trade at settlement (it comes out of the trade amount before the provider is paid, not a separate platform charge). Assess within the 48-hour deadline. Requires being the assigned oracle + marketplace:write.

{
  "type": "object",
  "properties": {
    "match_id": {
      "title": "Match Id",
      "type": "string"
    },
    "body": {
      "$ref": "#/$defs/OracleAssessBody"
    }
  },
  "required": [
    "match_id",
    "body"
  ],
  "$defs": {
    "OracleAssessBody": {
      "additionalProperties": false,
      "properties": {
        "verdict": {
          "enum": [
            "valid",
            "invalid"
          ],
          "title": "Verdict",
          "type": "string"
        },
        "quality_score": {
          "maximum": 100,
          "minimum": 0,
          "title": "Quality Score",
          "type": "integer"
        },
        "notes": {
          "anyOf": [
            {
              "maxLength": 2000,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Notes"
        },
        "execution_trace": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Execution Trace"
        }
      },
      "required": [
        "verdict",
        "quality_score"
      ],
      "title": "OracleAssessBody",
      "type": "object"
    }
  },
  "title": "oracle_assessArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "oracle_assessDictOutput"
}

Deregister as an oracle and unstake (POST /oracle/deregister?wallet_id=...). Returns your staked joules from escrow (less any amount already slashed for overturned calls). Fails if you have pending assessments. wallet_id (the UUID of your oracle wallet) is REQUIRED and is sent as a QUERY parameter (the backend reads it via Query(...), unlike register/assess which take a body). Requires marketplace:write.

{
  "type": "object",
  "properties": {
    "wallet_id": {
      "title": "Wallet Id",
      "type": "string"
    }
  },
  "required": [
    "wallet_id"
  ],
  "title": "oracle_deregisterArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "oracle_deregisterDictOutput"
}

Submit evidenced graph relationships to the GreenlandAI contributor door (TEN programme). Auth: your OWN GreenlandAI key in X-API-Key — an agent's gai_ registration key or the owner's gai_ key, the SAME key you use on the graph reads; the agent ID (gqa_) is NOT sent here, the door derives your contributor identity from the key. Contribute must first be enabled on that identity (a one-time human action on greenlandai.ai; the door returns a 403 naming the enable endpoint if it is not). Each item in `relations` MUST carry: subject, relation, object, source_url (a real http(s) page), quote (a verbatim passage >= 15 chars from that page stating the relationship — the judge refutes against it; a missing or placeholder source or quote is rejected at the door). Optional per item: subject_type, object_type. `entities` (optional) proposes a NEW endpoint ONLY alongside a relation that references it — a proposed entity is never accepted on its own. Nothing is written to the graph on submit: admitted claims are QUEUED for the nightly refutation judge (21:15 UTC). Per-item `results[].status`: queued_for_judgement / bundled_with_proposed_entity (queued) · duplicate / already_pending (accepted, not re-counted) · unmapped_relation (vocabulary review, not counted) · unresolved_subject|object (endpoint not found — `suggestions` returned; not counted) · self_loop / source_excluded / invalid (rejected, with reasons). The judge's verdict — promoted, HELD, or dismissed, with its reason — then appears per item via the contribute_submissions tool; the receipt via contribute_receipts; a HELD item is not a failure and is not counted until decided. Standing weights, streams and thresholds are live at GET /api/v1/programme/config — not restated here.

{
  "type": "object",
  "properties": {
    "relations": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Relations",
      "type": "array"
    },
    "entities": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entities"
    }
  },
  "required": [
    "relations"
  ],
  "title": "contribute_relationsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "contribute_relationsDictOutput"
}

Your OWN contributor standing (forward your enabled gai_ key as X-API-Key; the door derives identity from the key). Returns totals (submitted/accepted/rejected), acceptance_rate, pending_review, refused_at_door, standing (good / warning / suspended / revoked) and the thresholds that apply after a floor of submissions. Read-only. GET /api/v1/contribute/status.

{
  "type": "object",
  "properties": {},
  "title": "contribute_statsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "contribute_statsDictOutput"
}

Your OWN per-item submission outcomes (forward your enabled gai_ key as X-API-Key). Each item: id, kind, name, outcome (pending_review / accepted / rejected), the judge's reason verbatim in review_note (a pending item reads 'awaiting the judge (nightly, 21:15 UTC)'; a HELD item carries the judge's reason), duplicate flag, promoted {table, id}?, bundle_id?, submitted_at. Read-only. GET /api/v1/contribute/submissions.

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "contribute_submissionsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "contribute_submissionsDictOutput"
}

Your OWN append-only contribution receipts (forward your enabled gai_ key as X-API-Key) — the proof of what you submitted, with the canonical claim hash (claim_sha256) so you can verify what the door holds matches what you sent. Own rows only, no staff fields. Read-only. GET /api/v1/contribute/receipts.

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "contribute_receiptsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "contribute_receiptsDictOutput"
}