GreenlandAI

trade_settlement

YOUR OWN trade's settlement — every leg of a marketplace trade you were the BUYER or SELLER of (relays GET /api/v1/wallet/trade/{match_id}/settlement). Party-gated on the backend: a 404 means you were not a party to this match (it also hides whether the match exists at all — never a wallet id leaks). Returns your_role (buyer|seller), settled (true once the provider has been paid), leg_count, and legs[] — each leg is {type (provider_payout · oracle_fee · platform_fee · contract_fee · fund_fee · buyer_refund · dispute_refund · dispute_payout · …), recipient_role (a ROLE — provider · oracle · treasury · fee-collection · buyer — NEVER a wallet id; the sentinel "unknown" marks a leg type the backend does not map yet — logged loudly on their side, never money to the platform), amount, status, txid, anchor}, plus top-level all_anchored (true only when every leg's anchor is anchored). status is the LEDGER state of the leg (the money has moved once it reads completed); txid is written at BROADCAST, not at confirmation — so a leg can be settled with txid NULL (not broadcast yet — typically under a minute — OR its anchor dead-lettered) or carry a txid not yet on chain. A null txid on a fresh read is NOT a missing or failed leg: read anchor, the state to act on — queued | confirming | confirmed → poll (~30 s); anchored → verify the leg's txid on chain yourself (e.g. the verify_proof tool with the txid) — you don't have to trust us; failed | cancelled → the ledger leg settled but its anchor dead-lettered and will NOT reach the chain by itself (escalate); none → no anchor was attempted; unknown → a queue state the view does not recognise. This is the trade-WIDE view: deposit_status and a single transfer's status show only your own leg, not the payout or fees. Own trades only. Bearer or agent key required. CONTRACT SECTION — top-level contract, separate from legs[]: the on-chain escrow CONTRACT's own legs. They move no joules and have no recipient, so they never change settled, leg_count or all_anchored. contract: null = no escrow contract was recorded for this trade — a LEDGER-LANE trade (the default lane, escrow_bsv_state "NO_CONTRACT"; see market_request): normal, not a failure, and the settled legs[] are the record. Otherwise {version (the contract build), state (its latest state), closed (a FINAL leg exists: RELEASED · REFUNDED · SPLIT · TIMEOUT_REFUNDED · AUTO_REFUNDED), closed_on_chain (that final leg is anchored), closing_txid, legs[{state, txid, anchor (anchored · confirming · unknown), final}]}. An administrative closure is not a final leg, so it reads closed=false. verify_proof with the match_id reports the same trade's contract release as release_anchor_status (ledger_lane on a ledger-lane trade).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`match_id`	Yes

Output Schema

TableJSON Schema

Name	Required	Description
`legs`	No
`settled`	No
`contract`	No	the escrow CONTRACT's own chain legs {version, state, closed, closed_on_chain, closing_txid, legs[]}; null = no escrow contract was recorded (a ledger-lane trade)
`match_id`	No
`leg_count`	No
`your_role`	No
`all_anchored`	No	true only when every leg's anchor is 'anchored'

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 25, 2026

addedOutput schema / properties / contract

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "the escrow CONTRACT's own chain legs {version, state, closed, closed_on_chain, closing_txid, legs[]}; null = no escrow contract was recorded (a ledger-lane trade)",
+  "title": "Contract"
+}

AddedSep 23, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and meets it: it discloses party-gated 404 behavior (hiding match existence), the meaning of settled and all_anchored, the broadcast-vs-confirmation timing of txid, that a null txid is not a failure, and the ledger-lane 'contract: null' case as normal. It also differentiates contract legs from settlement legs and states auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and is organized into a main results section and a contract section, but it is exceptionally long and repeats some information (e.g., role explanations in legs and contract). While the density is justified by the tool's complexity, it could be tightened by leaving field-level return details to the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for an agent to call it safely: auth, gating, error semantics, field interpretations, polling guidance, escalation paths, and relation to verify_proof and deposit_status are all present. With an output schema present, the description goes beyond what is required and covers edge cases like dead-lettered anchors and no-contract trades.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description is the only source of parameter meaning. It clarifies that match_id is the trade identifier from the marketplace and that passing a match_id you are not a party to yields a 404, so the parameter semantics are workable. It doesn't provide an example or acquisition path, but the context from siblings (market_match) fills that gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: retrieving the settlement legs of a marketplace trade the caller was buyer or seller of. It explicitly scopes to 'YOUR OWN trade' and contrasts with deposit_status and a single transfer's status, distinguishing this tool's trade-wide view from siblings. The relayed endpoint is even cited.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states when to use the tool: for the trade-wide settlement view, not just one leg, and only for own trades, with bearer or agent key required. It advises polling when anchor is queued/confirming/confirmed, using verify_proof for on-chain verification, and escalating on failed/cancelled anchors, and contrasts with deposit_status and single-transfer status for narrower views.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All GreenlandAI tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?