xrpl-referee

Hire and Pay

hire_and_pay

One-call shortcut to register an escrow vault AND get the ready-to-sign transaction.

This combines create_escrow_vault() + prepare_escrow() into a single call. The agent only needs to sign the returned transaction and confirm it — no manual XRPL transaction construction required.

Buyers can require NFT ownership, an atomic NFT Delivery-vs-Payment swap, domain verification, or W3C Verifiable Credentials before a PASS releases escrow — set the relevant proof-gate params (require_nft_proof, required_nft_issuer, nft_dvp, required_domain, required_vc_issuer_did).

White-label / headless integration:

Pass callback_url to receive webhook POSTs on all state changes.
Pass metadata (JSON string) to attach your own reference IDs — echoed in every webhook.

Typical flow:

hire_and_pay() — register vault, get ready-to-sign EscrowCreate tx
Sign transaction with your wallet and submit to XRPL
confirm_escrow_transaction(escrow_id, tx_hash) — activate the vault
Worker submits work, agent calls evaluate_escrow_work() to release payment

Returns: escrow_id, transaction (ready-to-sign), condition, cancel_after_human, next_step instructions.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`task`	Yes	Detailed description of what the worker must deliver. The AI referee evaluates against this — be precise.
`nft_dvp`	No	Atomic NFT swap: worker must transfer a specific NFT to the buyer before payment releases. On PASS the vault enters PASS_AWAITING_NFT; worker registers their NFTokenCreateOffer and payment auto-releases when buyer accepts.
`fee_hash`	No	64-char hex hash of your $0.10 payment (XRP/RLUSD/USDC) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit to use free tier (if eligible).
`metadata`	No	Optional JSON string of key/value pairs to attach to this escrow and echo back in every webhook payload. Use to round-trip your own reference numbers (invoice_id, po_number, tenant_id, order_ref, etc.). Example: '{"invoice_id": "INV-2026-0042"}'.
`escrow_id`	Yes	Unique receipt code for this escrow, e.g. AT-7X9K-2MQ4. Must be unique.
`amount_xrp`	Yes	Amount of XRP to lock in escrow as the bounty.
`buyer_name`	No	Your name or agent identifier.
`callback_url`	No	HTTPS endpoint on your server to receive webhook POST notifications on escrow state changes (funded, PASS, FAIL, expired). Use this for white-label integrations where you handle all user-facing surfaces yourself. Payload: {escrow_id, event, verdict, timestamp, metadata}.
`proof_policy`	No	When multiple proof gates are set: 'ALL' (default) requires every gate to pass; 'ANY' requires at least one.	ALL
`buyer_address`	Yes	Your XRPL wallet address (r...) — you are the buyer.
`worker_address`	Yes	XRPL address (r...) of the worker to hire directly. Get this from direct_hire() or award_job().
`required_domain`	No	Worker must have their XRPL wallet domain field pointing to this domain. Pass 'ANY' to require any verified domain.
`cancel_after_hrs`	No	Hours until escrow auto-cancels if worker doesn't deliver. Default 168 = 7 days.
`require_consensus`	No	Require consensus between Gemini Flash AND Gemini Pro. Both must agree on PASS; split verdict returns conservative FAIL. Fee: $0.25 (vs $0.10 standard).
`require_nft_proof`	No	Worker must own an NFT from any trusted issuer (or from required_nft_issuer if set) to receive payment.
`required_nft_issuer`	No	Restrict NFT proof to NFTs minted by this XRPL wallet address.
`required_vc_issuer_did`	No	Worker must present a W3C Verifiable Credential JWT issued by this DID.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 20, 2026

addedInput schema / properties / callback_url

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "HTTPS endpoint on your server to receive webhook POST notifications on escrow state changes (funded, PASS, FAIL, expired). Use this for white-label integrations where you handle all user-facing surfaces yourself. Payload: {escrow_id, event, verdict, timestamp, metadata}."
+}

addedInput schema / properties / metadata

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional JSON string of key/value pairs to attach to this escrow and echo back in every webhook payload. Use to round-trip your own reference numbers (invoice_id, po_number, tenant_id, order_ref, etc.). Example: '{\"invoice_id\": \"INV-2026-0042\"}'."
+}

Changed7 schema fields changedSep 19, 2026

addedInput schema / properties / nft_dvp

Added value: +{
+  "default": false,
+  "description": "Atomic NFT swap: worker must transfer a specific NFT to the buyer before payment releases. On PASS the vault enters PASS_AWAITING_NFT; worker registers their NFTokenCreateOffer and payment auto-releases when buyer accepts.",
+  "type": "boolean"
+}

addedInput schema / properties / proof_policy

Added value: +{
+  "default": "ALL",
+  "description": "When multiple proof gates are set: 'ALL' (default) requires every gate to pass; 'ANY' requires at least one.",
+  "enum": [
+    "ALL",
+    "ANY"
+  ],
+  "type": "string"
+}

addedInput schema / properties / require_consensus

Added value: +{
+  "default": false,
+  "description": "Require consensus between Gemini Flash AND Gemini Pro. Both must agree on PASS; split verdict returns conservative FAIL. Fee: $0.25 (vs $0.10 standard).",
+  "type": "boolean"
+}

addedInput schema / properties / require_nft_proof

Added value: +{
+  "default": false,
+  "description": "Worker must own an NFT from any trusted issuer (or from required_nft_issuer if set) to receive payment.",
+  "type": "boolean"
+}

addedInput schema / properties / required_domain

Added value: +{
+  "default": "",
+  "description": "Worker must have their XRPL wallet domain field pointing to this domain. Pass 'ANY' to require any verified domain.",
+  "type": "string"
+}

addedInput schema / properties / required_nft_issuer

Added value: +{
+  "default": "",
+  "description": "Restrict NFT proof to NFTs minted by this XRPL wallet address.",
+  "type": "string"
+}

addedInput schema / properties / required_vc_issuer_did

Added value: +{
+  "default": "",
+  "description": "Worker must present a W3C Verifiable Credential JWT issued by this DID.",
+  "type": "string"
+}

Changed1 schema field changedAug 21, 2026

changedInput schema / properties / fee_hash / description

Previous value: -"64-char hex hash of your 0.1 XRP payment to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit to use free tier (if eligible)."New value: +"64-char hex hash of your $0.10 payment (XRP/RLUSD/USDC) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit to use free tier (if eligible)."

AddedAug 18, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description explains the compound behavior: it registers a vault and returns a ready-to-sign transaction, requiring the agent to sign, submit, and confirm before the vault activates. It also discloses proof-gating behavior, webhook/callback behavior, and the return payload, which go well beyond the annotations.

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

Conciseness5/5

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

The description is well organized with a lead summary, proof-gate context, white-label bullet points, a numbered typical flow, and an explicit return list. It is long but every section earns its place for a 17-parameter orchestration tool.

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?

Given an output schema and a fully described input schema, the description adds the missing procedural context: signing the transaction, confirming it, and later evaluating work. It is complete enough for an agent to invoke and follow through the workflow.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds high-level grouping of proof-gate parameters and notes white-label use of callback_url and metadata, but this mostly restates schema descriptions rather than adding new meaning.

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 opens with a specific verb and resource: 'register an escrow vault AND get the ready-to-sign transaction,' and explicitly names the two sibling operations it combines (create_escrow_vault + prepare_escrow). This makes the tool's role unmistakable and distinct from those siblings.

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

Usage Guidelines4/5

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

It clearly positions the tool as a one-call shortcut that combines create_escrow_vault() and prepare_escrow(), and gives a typical flow with downstream confirm_escrow_transaction() and evaluate_escrow_work(). It does not explicitly state when to avoid it or when to use the individual calls instead, so it stops short of a full when-to-use/when-not-to-use guide.

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

All xrpl-referee 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.