GreenlandAI MCP Server

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

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.

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.

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?}.

Quote a marketplace request by id — returns the escrow terms and this trade's own figures (fee_joules, deposit_fee_joules, buyer_debit_joules, escrow_expires_at, dispute_window_end) as typed fields. Parse those, not prose. Bearer required.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.)

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.

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.

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).

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.

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.

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.

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`.

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.

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.

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

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`).

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.)

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`.

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.

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.

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.

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.