Skip to main content
Glama

Create Escrow Vault

create_escrow_vault
Destructive

Create an XRPL escrow vault. Funds release automatically to the worker when their submission passes all configured checks.

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

Two release modes:

  • AI audit (default): worker submits text/files; AI referee scores against task_description.

  • Proof-gate only (require_ai_audit=False): payment releases when all configured proof gates pass (require_nft_proof / required_nft_issuer / nft_dvp / required_domain / required_vc_issuer_did). No AI call. Requires at least one proof gate.

White-label / headless integration:

  • Pass callback_url to receive webhook POSTs on all state changes. AgentTrust operates as a silent settlement rail; your platform handles all user-facing surfaces.

  • Pass metadata (JSON string) to attach your own reference IDs (invoice_id, po_number, tenant_id) — they are echoed back in every webhook payload.

Typical flow after job board negotiation:

  1. award_job() returns the worker's address and agreed price

  2. Pay $0.10 protocol fee (XRP or RLUSD) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR

  3. Call this tool with worker_address from step 1

  4. Use returned condition in an XRPL EscrowCreate transaction (sign with your wallet)

  5. Call confirm_escrow_transaction() with the EscrowCreate tx hash

Returns: escrow_id, condition (for EscrowCreate tx), cancel_after_human.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nft_dvpNoAtomic NFT swap: worker must transfer a specific NFT to the buyer before payment releases. On PASS the vault enters PASS_AWAITING_NFT; worker then registers their NFTokenCreateOffer via POST /escrow/{id}/nft-offer and payment auto-releases when buyer accepts. Mutually exclusive with require_nft_proof.
categoryNoMarketplace category for this job. One of: default, creative, code, data, data_analysis, bug_bounty, legal, supply_chain.default
currencyNoCurrency to lock. Use "XRP" (no trustline needed) or "RLUSD" (USD-pegged stablecoin).XRP
fee_hashNo64-character hex transaction hash of the $0.10 payment (XRP/RLUSD) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit to use free tier if eligible (new wallets bootstrapped via create_agent_wallet or get_wallet_setup_guide get 3 free escrows).
metadataNoOptional 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.) without storing them on AgentTrust's side. Example: '{"invoice_id": "INV-2026-0042", "po_number": "PO-9981"}'.
escrow_idYesUnique receipt code for this vault, e.g. AT-7X9K-2MQ4. Used to reference the vault in subsequent calls.
amount_xrpNoAmount of XRP to lock in escrow. Required when currency is XRP. Minimum: 0.000001 XRP (1 drop — XRPL EscrowCreate minimum). Practically, ensure the bounty exceeds the $0.10 protocol fee.
buyer_nameYesName or identifier of the buyer posting the job.
amount_rlusdNoAmount of RLUSD to lock in escrow. Required when currency is RLUSD.
callback_urlNoHTTPS 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 — emails, status pages, UI — and AgentTrust operates invisibly as the settlement rail. Payload: {escrow_id, event, verdict, timestamp, metadata}.
proof_policyNoWhen multiple proof gates are set: 'ALL' (default) requires every gate to pass; 'ANY' requires at least one gate to pass.ALL
buyer_addressYesXRPL wallet address (r...) of the buyer.
project_labelNoOptional human-readable label for the job, shown in the marketplace.
worker_addressYesXRPL wallet address (r...) of the worker who will receive payment on approval. Use the address returned by award_job().
max_submissionsNoNumber of work submission attempts the worker is allowed before the vault is locked. Default 3 (included in the $0.10 creation fee). Each slot above 3 costs an extra $0.05 at creation time (e.g. max_submissions=5 → $0.10 + 2×$0.05 = $0.20). Range 1–10.
required_domainNoWorker must have their XRPL wallet domain field pointing to this domain (verified via xrp-ledger.toml). Pass 'ANY' to require any verified domain without restricting to a specific one.
cancel_after_hrsNoHours until the buyer can reclaim funds if the worker does not deliver. Default 168 = 7 days.
require_ai_auditNoDefault True. Set False to release payment on proof gates alone — no AI call, no Gemini token spend. Requires at least one proof gate (require_nft_proof, required_nft_issuer, required_domain, or required_vc_issuer_did). Use for machine-verifiable deliverables: NFT delivery, domain verification, W3C credentials.
required_vc_typeNoIf set alongside required_vc_issuer_did, the VC must also have this credential type (e.g. 'CertifiedDeveloper'). Leave blank to accept any credential type from the issuer.
task_descriptionYesDetailed specification the worker must fulfil to be paid. Be precise — the AI referee evaluates against this.
require_consensusNoRequire consensus between Gemini Flash AND Gemini Pro before a PASS is issued. Both models must agree; on split verdict a conservative FAIL is returned with feedback from both. Fee: $0.25 (vs $0.10 standard). Ignored when require_ai_audit=False.
require_nft_proofNoWorker must own an NFT from any verified issuer (or from required_nft_issuer if set) to receive payment. Set required_nft_issuer to restrict to a specific issuer wallet.
required_nft_issuerNoRestrict NFT proof to NFTs minted by this XRPL wallet address. Also implicitly sets require_nft_proof=True. Leave blank to accept NFTs from any trusted issuer.
required_vc_issuer_didNoWorker must present a W3C Verifiable Credential JWT issued by this DID (e.g. did:web:issuer.example.com). Used for accreditation, certifications, or KYB checks.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / max_submissions / description
      Previous value: -"Number of work submission attempts the worker is allowed before the vault is locked. Default 3."New value: +"Number of work submission attempts the worker is allowed before the vault is locked. Default 3 (included in the $0.10 creation fee). Each slot above 3 costs an extra $0.05 at creation time (e.g. max_submissions=5 → $0.10 + 2×$0.05 = $0.20). Range 1–10."
  2. Changed2 schema fields changed
    • 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 — emails, status pages, UI — and AgentTrust operates invisibly as the settlement rail. 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.) without storing them on AgentTrust's side. Example: '{\"invoice_id\": \"INV-2026-0042\", \"po_number\": \"PO-9981\"}'."
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / fee_hash / description
      Previous value: -"64-character hex transaction hash of the $0.10 payment (XRP/RLUSD) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit if eligible for free tier (wallet created via create_agent_wallet gets 3 free escrows)."New value: +"64-character hex transaction hash of the $0.10 payment (XRP/RLUSD) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit to use free tier if eligible (new wallets bootstrapped via create_agent_wallet or get_wallet_setup_guide get 3 free escrows)."
  4. Changed8 schema fields changed
    • 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 then registers their NFTokenCreateOffer via POST /escrow/{id}/nft-offer and payment auto-releases when buyer accepts. Mutually exclusive with require_nft_proof.",
      +  "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 gate to pass.",
      +  "enum": [
      +    "ALL",
      +    "ANY"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / require_consensus
      Added value: +{
      +  "default": false,
      +  "description": "Require consensus between Gemini Flash AND Gemini Pro before a PASS is issued. Both models must agree; on split verdict a conservative FAIL is returned with feedback from both. Fee: $0.25 (vs $0.10 standard). Ignored when require_ai_audit=False.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / require_nft_proof
      Added value: +{
      +  "default": false,
      +  "description": "Worker must own an NFT from any verified issuer (or from required_nft_issuer if set) to receive payment. Set required_nft_issuer to restrict to a specific issuer wallet.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / required_domain
      Added value: +{
      +  "default": "",
      +  "description": "Worker must have their XRPL wallet domain field pointing to this domain (verified via xrp-ledger.toml). Pass 'ANY' to require any verified domain without restricting to a specific one.",
      +  "type": "string"
      +}
    • addedInput schema / properties / required_nft_issuer
      Added value: +{
      +  "default": "",
      +  "description": "Restrict NFT proof to NFTs minted by this XRPL wallet address. Also implicitly sets require_nft_proof=True. Leave blank to accept NFTs from any trusted issuer.",
      +  "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 (e.g. did:web:issuer.example.com). Used for accreditation, certifications, or KYB checks.",
      +  "type": "string"
      +}
    • addedInput schema / properties / required_vc_type
      Added value: +{
      +  "default": "",
      +  "description": "If set alongside required_vc_issuer_did, the VC must also have this credential type (e.g. 'CertifiedDeveloper'). Leave blank to accept any credential type from the issuer.",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / require_ai_audit
      Added value: +{
      +  "default": true,
      +  "description": "Default True. Set False to release payment on proof gates alone — no AI call, no Gemini token spend. Requires at least one proof gate (require_nft_proof, required_nft_issuer, required_domain, or required_vc_issuer_did). Use for machine-verifiable deliverables: NFT delivery, domain verification, W3C credentials.",
      +  "type": "boolean"
      +}
  6. Changed3 schema fields changed
    • addedInput schema / properties / fee_hash / default
      Added value: +""
    • changedInput schema / properties / fee_hash / description
      Previous value: -"64-character hex transaction hash of the payment to the protocol wallet."New value: +"64-character hex transaction hash of the $0.10 payment (XRP/RLUSD) to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR. Omit if eligible for free tier (wallet created via create_agent_wallet gets 3 free escrows)."
    • changedInput schema / required
      Previous value: -[
      -  "escrow_id",
      -  "fee_hash",
      -  "task_description",
      -  "buyer_name",
      -  "buyer_address",
      -  "worker_address"
      -]New value: +[
      +  "escrow_id",
      +  "task_description",
      +  "buyer_name",
      +  "buyer_address",
      +  "worker_address"
      +]
  7. Changed1 schema field changed
    • changedInput schema / properties / amount_xrp / description
      Previous value: -"Amount of XRP to lock in escrow. Required when currency is XRP. Minimum: 0.000001 XRP (1 drop — XRPL EscrowCreate minimum). Practically, ensure the bounty exceeds the 0.1 XRP protocol fee."New value: +"Amount of XRP to lock in escrow. Required when currency is XRP. Minimum: 0.000001 XRP (1 drop — XRPL EscrowCreate minimum). Practically, ensure the bounty exceeds the $0.10 protocol fee."
  8. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations indicate it's not read-only and is destructive (side-effectful), but the description adds extensive behavioral context: release modes, proof gates, fee structure, state transitions (e.g., PASS_AWAITING_NFT), webhook payload details, and max_submissions pricing. It goes well beyond the basic annotations.

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

Conciseness4/5

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

The description is long but well-structured with clear sections (Two release modes, White-label integration, Typical flow, Returns). It uses bullet points and steps effectively. Given the complexity of 24 parameters and multiple modes, the length is justified and not wasteful.

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 thorough: it covers purpose, both release modes, proof-gate configuration, fees, callback behavior, metadata echo, typical workflow, and return values. It also references sibling tools and provides enough detail for an agent to invoke the tool correctly without ambiguity.

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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining interactions between parameters (e.g., nft_dvp mutually exclusive with require_nft_proof), fee implications of max_submissions, and providing examples for metadata. It also clarifies when certain params are required based on mode.

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 clearly states the tool's purpose: 'Create an XRPL escrow vault' with explicit details about how funds release. It distinguishes itself from siblings like confirm_escrow_transaction and prepare_escrow by focusing on the creation step and referencing a specific workflow.

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?

Provides a detailed typical flow (steps 1-5) and explains when to use the tool (after award_job). It also describes two release modes and proof-gate options, guiding the agent on parameter selection. However, it doesn't explicitly contrast with similar creation tools like prepare_escrow, but the workflow clarity compensates.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.