plugins:
  entries:
    escrow:
      type: mcp
      config:
        command: npx
        args: ["-y", "@decanus-labs/escrow-mcp"]
        env:
          PRIVATE_KEY: "0x..."

Optional env vars: RPC_URL (default: https://sepolia.base.org), CONTRACT_ADDRESS (default: v2 deployment).

Tools

Write Tools

`create_escrow`

Buyer creates an escrow, depositing ETH as payment.

Param	Type	Required	Description
`seller`	string	yes	Seller's Ethereum address
`arbiter`	string	yes	Arbiter's Ethereum address (dispute resolver)
`paymentAmountEth`	string	yes	Payment in ETH (e.g. `"0.01"`)
`durationSeconds`	number	yes	Deadline in seconds from now

`accept_escrow`

Seller accepts by depositing a stake >= the payment amount.

Param	Type	Required	Description
`escrowId`	number	yes	Escrow ID
`stakeAmountEth`	string	yes	Stake in ETH (must be >= payment)

`deliver_work`

Seller submits delivery proof. Starts a 24h buyer review window.

Param	Type	Required	Description
`escrowId`	number	yes	Escrow ID
`deliveryHash`	string	yes	bytes32 hex or plain string (auto-hashed via keccak256)

`complete_escrow`

Buyer approves delivery. Releases payment + seller stake to seller.

Param	Type	Required	Description
`escrowId`	number	yes	Escrow ID

`dispute_escrow`

Either party raises a dispute. Arbiter must resolve.

Param	Type	Required	Description
`escrowId`	number	yes	Escrow ID
`reason`	string	no	Human-readable reason (stored off-chain)

`refund_expired_escrow`

Anyone triggers after deadline. Buyer gets payment back, seller stake burns.

Param	Type	Required	Description
`escrowId`	number	yes	Escrow ID

Read Tools

`get_escrow`

Fetch escrow state. Returns state label, participants, amounts, deadlines (ISO + relative), delivery hash, and suggested next actions.

Param	Type	Required	Description
`escrowId`	number	yes	Escrow ID

`list_escrows`

Paginated scan of recent escrows.

Param	Type	Required	Description
`limit`	number	no	Max results (default 10, max 50)
`state`	string	no	Filter: `AWAITING_SELLER`, `FUNDED`, `DELIVERED`, `COMPLETED`, `DISPUTED`, `REFUNDED`, `BURNED`
`participant`	string	no	Filter by address (buyer, seller, or arbiter)

Escrow States

AWAITING_SELLER → FUNDED → DELIVERED → COMPLETED
                    ↓          ↓
                 DISPUTED   DISPUTED
                    ↓
                 BURNED (after deadline)

AWAITING_SELLER -- buyer deposited, waiting for seller to stake
FUNDED -- both deposited, seller can deliver or deadline triggers burn
DELIVERED -- seller submitted proof, 24h grace for buyer to approve or dispute
COMPLETED -- buyer approved, seller received payment + stake
DISPUTED -- arbiter must resolve
BURNED -- deadline expired while FUNDED, buyer refunded, seller stake locked permanently

Common Flows

Happy path: hire an agent, pay on delivery

1. create_escrow(seller=0x..., arbiter=0x..., paymentAmountEth="0.01", durationSeconds=86400)
2. Seller calls: accept_escrow(escrowId=0, stakeAmountEth="0.01")
3. Seller calls: deliver_work(escrowId=0, deliveryHash="ipfs://QmProof...")
4. Buyer calls: complete_escrow(escrowId=0)
   → Seller receives 0.02 ETH (payment + stake returned)

Dispute path

1. create_escrow(...) → accept_escrow(...)
2. Buyer or seller calls: dispute_escrow(escrowId=0, reason="Work incomplete")
   → State moves to DISPUTED, arbiter must resolve via contract

Expired refund (seller no-show)

1. create_escrow(...) → accept_escrow(...)
2. Deadline passes with no delivery
3. Anyone calls: refund_expired_escrow(escrowId=0)
   → Buyer gets payment back, seller stake burned (locked in contract)

Check status

get_escrow(escrowId=0)
→ Returns state, deadlines, next valid actions

Notes

All ETH amounts are strings to avoid precision issues. Use "0.01" not 0.01.
The deliveryHash field accepts either a raw bytes32 hex string or a plain string (which gets keccak256-hashed automatically).
Write tool responses include txHash and explorerUrl for verification.
Each server instance uses one signer (the PRIVATE_KEY). Run separate instances for buyer and seller roles.
Currently Base Sepolia testnet only. ETH-native, not stablecoin.

escrow-mcp

Escrow MCP Server

Start the Server