Hire and Pay
hire_and_payOne-call shortcut to register an escrow vault AND get the ready-to-sign transaction. Free to try: pass network='testnet' (see create_testnet_wallet / try_testnet_demo).
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).
Structured criteria: pass criteria as a list of strings or typed dicts. Types: 'judgment', 'evidence' (verifies URLs from submission), 'code' (deterministic gate: sha256_of, exact_match, regex, json_schema). INCONCLUSIVE verdicts do not consume an attempt for the first 3 per vault; subsequent INCONCLUSIVEs count as an attempt.
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task": "<task>",
"buyer_address": "<buyer_address>",
"amount_xrp": "<amount_xrp>",
"worker_address": "<worker_address>"
},
"name": "hire_and_pay"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Detailed description of what the worker must deliver. The AI referee evaluates against this — be precise. | |
| network | No | 'mainnet' (default) or 'testnet'. Use 'testnet' for free testing — no real XRP, no fees. Create a testnet wallet first with create_testnet_wallet(). | mainnet |
| 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. | |
| criteria | No | Optional list of evaluation criteria. Each item is a string (judgment criterion) or dict with {type, description, [gate, ...]}. Types: 'judgment', 'evidence' (URL verification), 'code' (deterministic gate: sha256_of, exact_match, regex, json_schema). INCONCLUSIVE verdicts do not consume an attempt for the first 3 per vault; subsequent INCONCLUSIVEs count as an attempt. | |
| fee_hash | No | 64-char hex hash of your $0.10 payment to rmcSrkpZ2i2kuvtCPeTVetee9SixP4djR (XRP or RLUSD on XRPL) or USDC on Base (chain 8453, 0x-prefixed tx hash). Omit to use free tier if eligible (new agent wallets and new Pro accounts get 3 free escrows, each including the AI check). | |
| metadata | No | Optional key/value pairs to attach to this escrow and echo back in every webhook payload. Pass as a dict or JSON string. 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 | No | Unique receipt code for this escrow, e.g. AT-7X9K-2MQ4. Must be unique. Leave blank to auto-generate. | |
| 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}. | |
| external_ref | No | Reference to work found on another platform, e.g. 'upwork:123', 'github:org/repo#45'. Stored on the vault for your own tracking. | |
| external_url | No | URL of the original job listing (must start with https://). Informational — stored on the vault. | |
| proof_policy | No | When multiple proof gates are set: 'ALL' (default) requires every gate to pass; 'ANY' requires at least one. | ALL |
| release_mode | No | 'auto' (default): immediate release on PASS. 'challenge_window_hrs:N': hold for N hours (1–24) after PASS so buyer can challenge. | auto |
| 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. | |
| delegate_address | No | XLS-75 delegated agent XRPL address. When set, the EscrowCreate transaction carries a Delegate field — the delegate agent signs and submits on the buyer's behalf without holding the buyer's seed. The buyer must first submit a DelegateSet granting EscrowCreate permission to this address. | |
| deliverable_type | No | Type of deliverable: 'work' (default), 'code', 'data', 'nft'. | work |
| counterparty_type | No | Whether the worker is an 'agent' (default) or 'human'. Affects email copy and worker_url instructions. | agent |
| 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
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||