create_escrow
[FIAT ESCROW] Create a fiat escrow payment. Returns deposit instructions (CLABE for MXN, wire for USD).
HOW FUNDING WORKS (IMPORTANT):
The MCP does NOT fund fiat escrows. After creation, this tool returns deposit instructions (CLABE or wire details).
The BUYER must deposit funds themselves via SPEI or bank wire. The platform detects the deposit automatically.
Your job as the agent: present the CLABE/wire instructions to the user and tell them to make the deposit.
To check if the deposit arrived, use check_status.
For web3 wallet-to-wallet escrows where the AGENT can fund, use create_web3_escrow + fund_web3_escrow instead.
PAYMENT TYPES:
- 'standard' (default): General marketplace escrow. Only requires amount, currency, payer/recipient emails.
- 'vehicle_verification': Car purchase escrow. REQUIRES: vehicle_vin, vehicle_make, vehicle_model. Also accepts: vehicle_year, vehicle_plate, vehicle_color, vehicle_mileage.
- 'mechanical_inspection': Similar to vehicle but focused on inspection.
CURRENCY FLOWS:
- MXN → MXN: Buyer deposits via SPEI, seller receives SPEI payout (Route A1)
- USD → MXN: Buyer wires USD, seller receives MXN SPEI payout (Route A2)
- USD → USD: Buyer wires USD, seller receives USD wire payout (Route A3)
- MXN → USD: Buyer deposits MXN SPEI, seller receives USD wire (Route A4)
IMPORTANT CONSTRAINTS:
- For MXN payouts: seller MUST have a beneficiary_clabe (18-digit CLABE) registered BEFORE release. The seller registers it via their dashboard — do NOT ask the buyer for it.
- For USD payouts: seller MUST register a US bank account (external_account_id) via Bitso before release.
- Seller MUST complete KYC verification before funds can be released.
- NOT for crypto/wallet-to-wallet payments — use create_web3_escrow instead.
check_status
[FIAT ESCROW] Check full status of a fiat payment including deposit details, escrow state, and payout readiness. Use this to verify pre-conditions before calling release_funds. Returns: status, deposit CLABE/wire info, escrow blockchain IDs, payout status, and timeline. For web3 on-chain escrows, use check_web3_status instead.
release_funds
[FIAT ESCROW] Release escrowed funds to seller. Triggers on-chain escrow release + SPEI/wire payout.
PRE-CONDITIONS (ALL must be met for live payments):
1. Payment status must be 'in_custody' or 'ready_for_release'
2. Seller KYC must be 'approved' (seller must complete identity verification)
3. For MXN payouts: seller must have a beneficiary_clabe (18-digit CLABE) - check via check_status
4. For USD payouts: seller must have an external_account_id (US bank via Bitso)
5. For standard payments: buyer payer_approval must be true (unless vehicle_verification or ready_for_release)
If any pre-condition fails, use check_status to see what's missing, then guide the user to complete the requirement before retrying.
FLOW AFTER RELEASE:
1. On-chain escrow released (tokens return to bridge wallet)
2. Tokens transferred to Juno (MXNB) or Bitso (USDC)
3. Fiat payout initiated (SPEI to seller CLABE or USD wire)
4. Payment status → 'released' → 'completed'
upload_evidence
Upload evidence or documentation for a payment or escrow (works for both fiat and web3 escrows).
get_fx_rate
Get current FX rate between currencies (USD, MXN, USDC, MXNB). Useful for cross-border escrows.
list_payments
[FIAT ESCROW] List fiat payments. For on-chain escrows, use list_web3_escrows instead.
cancel_payment
[FIAT ESCROW] Cancel a pending fiat payment before deposit. Cannot cancel web3 escrows this way.
raise_dispute
[FIAT ESCROW] Raise dispute on a fiat payment. For web3 escrows, use dispute_web3_escrow instead.
request_refund
[FIAT ESCROW] Request refund for a fiat payment. Triggers SPEI/wire return to buyer.
create_web3_escrow
[WEB3 ESCROW] Create an on-chain escrow via platform relayer. The RELAYER pays gas and calls createEscrow.
WALLET MODEL (3-step process):
1. CREATE (this tool): Relayer wallet registers the escrow on-chain with payer/payee addresses. Gas paid by platform.
2. FUND: The PAYER wallet must call approve() + fundEscrow().
- For GASLESS via ZeroDev: Set use_zerodev=true so payer=smart account, then use fund_with_session_key
- For AGENTIC wallets (Coinbase AgentKit): Agent can sign approve+fund programmatically
- For HUMAN wallets (MetaMask, etc): MUST use the Kustodia web3 dashboard UI to approve+fund
3. RELEASE/DISPUTE (separate tools): Relayer wallet can release or dispute funded escrows
IMPORTANT: If you plan to fund via fund_with_session_key, you MUST set use_zerodev=true so the smart account is the payer.
SUPPORTED CHAINS: Arbitrum (42161), Base (8453), Polygon (137), Injective (1776)
SUPPORTED TOKENS: USDC, MXNB, USDT (varies by chain)
fund_web3_escrow
[WEB3 ESCROW] Fund an existing on-chain escrow by batching approve + fundEscrow.
FOR AGENTIC WALLETS (Coinbase AgentKit, server-side EOA).
Human users with browser wallets (MetaMask) should fund via the Kustodia web3 dashboard.
PRE-CONDITIONS:
1. Escrow must be in 'Created' status
2. The signing wallet must be the PAYER registered in the escrow
3. Wallet must have sufficient token balance
KEY SELECTION:
- If you pass agent_private_key, that key signs the tx (Coinbase AgentKit flow)
- If omitted, the platform relayer key signs (only works if relayer is the payer)
- For ZeroDev gasless funding, use fund_with_session_key instead
This tool automatically checks allowance, approves if needed, and calls fundEscrow.
release_web3_escrow
[WEB3 ESCROW] Release a FUNDED on-chain escrow — tokens go to the payee wallet.
PRE-CONDITIONS:
1. Escrow must be in 'Funded' status (payer has already called approve + fundEscrow from their wallet)
2. Only works for escrows created via Kustodia contracts
The platform relayer signs this transaction — no user wallet needed for release.
dispute_web3_escrow
[WEB3 ESCROW] Dispute a FUNDED on-chain escrow. Freezes the escrow for Kustodia mediation.
PRE-CONDITIONS:
1. Escrow must be in 'Funded' status
2. Reason must be at least 10 characters
After disputing, use upload_evidence to submit supporting documentation. Kustodia will mediate.
check_web3_status
[WEB3 ESCROW] Check on-chain escrow status from DB index. Fast lookup by escrow ID.
list_web3_escrows
[WEB3 ESCROW] List on-chain escrows. Filter by chain, status, wallet address. Returns indexed blockchain data.
get_web3_escrow
[WEB3 ESCROW] Read escrow data directly from the smart contract (real-time, on-chain). Use for verification.
create_session_key
[ZERODEV / ERC-4337] Create a scoped session key for gasless escrow funding.
The platform creates a ZeroDev smart account session key that ONLY allows:
1. approve(token, escrowContract, amount)
2. fundEscrow(escrowId)
SECURITY: No private keys are required or exposed. The platform's server-side key creates the session.
The session key expires in 24 hours. Gas is sponsored by Kustodia.
After creating, use fund_with_session_key with the returned session_id to fund escrows.
Supported chains: Arbitrum Sepolia (421614), Base Sepolia (84532).
fund_with_session_key
[ZERODEV / ERC-4337] Fund an on-chain escrow using a server-side session key.
PRE-CONDITIONS:
1. A session key must be created first via create_session_key (returns a session_id)
2. The smart account must hold sufficient tokens
3. The escrow must be in 'Created' status
SECURITY: No private keys required. The session_id references a server-stored session key.
Executes a BATCHED UserOperation: approve + fundEscrow in ONE transaction.
Gas is SPONSORED by Kustodia — no ETH needed in the smart account.
For direct wallet funding (Coinbase AgentKit), use fund_web3_escrow instead.
register_agent_wallet
[AGENT TRADING] Register your AI agent's wallet for discovery and trading.
Registered agents can be found by other agents via list_trade_offers.
This enables agent-to-agent escrow trading — each agent uses its own wallet.
HOW AGENTS TRADE:
1. register_agent_wallet — register your wallet for discovery
2. list_trade_offers — find open escrows or registered agents
3. create_web3_escrow — create an escrow with another agent as payee
4. fund_web3_escrow or fund_with_session_key — fund the escrow
5. accept_trade — verify your role in an escrow
6. release_web3_escrow — release funds after delivery
fund_agent_wallet
[AGENT FUNDING] Fund an agent wallet with USDC or MXNB via fiat on-ramp.
THREE PATHS TO FUND:
1. SPEI (MXN): deposit_method="spei" → Juno MXNB mint → [optional MXNB→USDC swap] → Agent Wallet
2. Wire (USD): deposit_method="wire" → Bitso USD→USDC → Agent Wallet
3. Direct crypto transfer (no tool needed — just send tokens to the wallet address)
Returns deposit instructions (CLABE for SPEI, or bank details for Wire).
Funds are automatically converted and transferred after deposit confirmation.
list_trade_offers
[AGENT TRADING] List open escrows and trade offers on-chain.
Reads directly from the KustodiaEscrowWeb3 smart contract to find:
- Created (unfunded) escrows — waiting for funding
- Funded escrows — active trades
Use this to discover trading opportunities before creating or accepting trades.
accept_trade
[AGENT TRADING] Check if you're the counterparty in a trade and get next steps.
Verifies:
- Whether your wallet is the payee in the escrow
- Current escrow status (Created, Funded, etc.)
- What actions you need to take next
Use this after creating or discovering an escrow to understand your role.
check_balance
[READ-ONLY] Check native (ETH) and ERC20 token balances for any wallet on supported chains.
Returns:
- Native balance (ETH/MATIC)
- ERC20 token balances (USDC, MXNB, USDT, etc.)
Supports all Kustodia chains: Arbitrum (42161), Base (8453), Polygon (137), Arbitrum Sepolia (421614), Base Sepolia (84532).
If no tokens specified, checks all configured tokens for the chain.
Useful to verify wallet has sufficient funds before escrow operations.
get_trust_score
[READ-ONLY] Get trust score and badge for any wallet address.
Aggregates data from all escrow activity — completion rate, dispute rate, volume, resolution time.
Badge levels: new (< 3 escrows), verified (≥ 3, 70%+ completion), trusted (≥ 10, 90%+ completion, < 10% disputes), elite (≥ 50, 95%+ completion, $10K+ volume).
Use before transacting to assess counterparty risk. Scores are cached for 1 hour.
Public profile: kustodia.app/trust/<wallet>
create_confidential_escrow
[CONFIDENTIAL ESCROW] Create a fully encrypted on-chain escrow using Fhenix FHE.
The escrow amount is encrypted BEFORE hitting the blockchain — no one can see it on Arbiscan.
Only the payer, payee, and platform can decrypt the amount.
Currently available on: Arbitrum Sepolia (421614) only.
Uses the ConfidentialEscrowV2 contract with CoFHE threshold encryption.
AFTER CREATION: Fund via fund_confidential_escrow, release via release_confidential_escrow.
fund_confidential_escrow
[CONFIDENTIAL ESCROW] Fund a confidential escrow using FHERC20 encrypted tokens.
Automates the 4-step FHERC20 flow:
1. Approve USDC for wrapper
2. Wrap USDC → cUSDC (encrypted token)
3. Approve cUSDC for escrow contract
4. Fund escrow with encrypted transfer — NO amounts in Transfer events
PRE-CONDITIONS:
- Escrow must be in 'Created' status
- Relayer wallet must have sufficient USDC balance
- Only Arbitrum Sepolia (421614)
release_confidential_escrow
[CONFIDENTIAL ESCROW] Release a funded confidential escrow with CoFHE decryption.
Decrypts the encrypted amount + fee server-side using the CoFHE threshold network,
then calls releaseEscrow with the decrypted values + cryptographic signatures.
The payee receives tokens via encrypted FHERC20 transfer — no amounts visible.
PRE-CONDITIONS:
- Escrow must be in 'Funded' status
- Only the payer, owner, or relayer can release
create_solana_blink
[SOLANA BLINKS] Create a Solana Blink escrow — shareable payment link for P2P transactions.
Creates an escrow on Solana and returns shareable URLs:
- Direct link (kustodia.app/blinks/...)
- Phantom deep link
- WhatsApp share link
- dial.to blink card URL
Buyer opens link → pays via Phantom wallet → funds locked in smart contract → seller releases after delivery.
Fees: 3% on release. Token: USDC on Solana.
get_escrow_evidence
[READ-ONLY] List all evidence files attached to an escrow.
Returns IPFS + GCS URLs, descriptions, types, and timestamps for each evidence item.
Works for both web3 and fiat escrows. IPFS URLs are preferred (always publicly accessible).
Useful for agents reviewing disputes or verifying delivery before releasing funds.
create_recurring_escrow
[RECURRING] Create a recurring escrow subscription — automated billing on interval.
Sets up a subscription that auto-creates escrow cycles at the specified interval.
Supports fiat (MXN SPEI, USD wire) and web3 (USDC, USDT, MXNB on-chain) payment methods.
MODES:
- delegated=true: Platform charges automatically (requires spending cap)
- delegated=false: Each cycle needs payer approval within 48h
MONETIZATION:
- Setup fee: 1% of first cycle
- Per-cycle fee: 0.5% of each payment
- Platform commission: 2% on release
pause_recurring
[RECURRING] Pause an active recurring subscription. Can be resumed later.
resume_recurring
[RECURRING] Resume a paused recurring subscription.
cancel_recurring
[RECURRING] Cancel a recurring subscription. In-progress cycles will complete, no new cycles created.
approve_cycle
[RECURRING] Approve a pending billing cycle (for non-delegated subscriptions). Must approve within 48h.
list_recurring
[RECURRING] List recurring subscriptions. Filter by status, user, or payee.
get_recurring_status
[RECURRING] Get full status of a recurring subscription including all cycle history, fees, and next billing date.