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.

Instructions

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.

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. Changed21 schema fields changedv3.1.0
    • addedInput schema / properties / amount_rlusd / title
      Added value: +"RLUSD Amount"
    • addedInput schema / properties / amount_xrp / title
      Added value: +"XRP Amount"
    • addedInput schema / properties / buyer_address / title
      Added value: +"Buyer XRPL Address"
    • 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}.",
      +  "title": "Callback URL"
      +}
    • addedInput schema / properties / cancel_after_hrs / title
      Added value: +"Cancel After (hours)"
    • addedInput schema / properties / category / title
      Added value: +"Job Category"
    • addedInput schema / properties / escrow_id / title
      Added value: +"Escrow ID"
    • 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)."
    • addedInput schema / properties / fee_hash / title
      Added value: +"XRPL Payment Hash"
    • 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."
    • 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\"}'.",
      +  "title": "Metadata (JSON string)"
      +}
    • 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.",
      +  "title": "NFT Delivery-vs-Payment",
      +  "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_ai_audit / title
      Added value: +"Require AI Audit"
    • 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.",
      +  "title": "Premium Consensus Audit",
      +  "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.",
      +  "title": "Require NFT Proof",
      +  "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.",
      +  "title": "Required NFT 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.",
      +  "title": "Required VC Issuer DID",
      +  "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.",
      +  "title": "Required VC Type",
      +  "type": "string"
      +}
    • addedInput schema / properties / worker_address / title
      Added value: +"Worker XRPL Address"
  2. Changed4 schema fields changedv2.2.0
    • 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)."
    • 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"
      +}
    • 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"
      +]
  3. First observedv0.1.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations declare the safety profile (destructive, non-idempotent, open-world), and the description adds genuine operational context beyond them: the $0.10 protocol fee and free-tier eligibility, per-slot cost for max_submissions above 3, the PASS_AWAITING_NFT state transition and follow-up nft-offer call, webhook event set, and the nft_dvp / require_nft_proof mutual exclusion. It does not spell out the refund/expiry/dispute path beyond cancel_after_hrs, so a 5 is not warranted.

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?

Front-loaded with the one-line purpose, then scoped sections for proof gates, release modes, and white-label integration. For a 24-parameter tool the length is justified, and each bullet carries distinct information. Minor redundancy between the proof-gate paragraph and the per-parameter descriptions keeps it from being maximally tight.

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?

An output schema exists, so return values need no prose. Given 24 parameters, the description covers what the schema cannot: pricing and free-tier logic, mode selection, gating rules, webhook payload contents, and state-machine side effects. Nothing an agent needs to invoke this correctly appears to be missing.

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 description coverage is 100%, so the baseline is 3, and the description clearly earns above that by grouping the proof-gate params (require_nft_proof / required_nft_issuer / nft_dvp / required_domain / required_vc_issuer_did) and explaining how require_ai_audit interacts with them and with proof_policy. It adds conceptual meaning (which params form a gate set, which combinations are required) rather than restating field text.

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

Purpose4/5

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

The opening sentence gives a specific verb and resource ("Create an XRPL escrow vault") and immediately explains the core behavior: funds release to the worker on a passing submission. It also lays out the two release modes, which orients the agent well. It never names the nearby siblings it must be picked over (prepare_escrow, hire_and_pay, direct_hire), so sibling differentiation is left implicit.

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?

Strong conditional guidance: default AI-audit mode vs. require_ai_audit=False proof-gate-only mode, with an explicit precondition (at least one proof gate) and a use case (machine-verifiable deliverables). callback_url and metadata are each tied to a concrete scenario (white-label/headless integration, reference-ID round-tripping). No explicit "do not use this when…" or named alternative tool, which keeps it out of 5 territory.

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