Escrow

Lock funds in a smart contract until work is delivered. The sender releases funds on completion, or refunds automatically after the deadline. Fee (0.5%) is only charged on release — refunds are free.

Lifecycle


Create → [Open] → Release (0.5% fee) → [Released]
                → Refund (after deadline, no fee) → [Refunded]

Create ETH Escrow


const deadline = Math.floor(Date.now() / 1000) + 86400 // 24 hours from now
 
const { escrowId, txHash } = await client.createEscrowETH(
  recipientAddress,
  ethers.parseEther('0.01'),
  deadline,
  { memo: 'build a REST API' }
)

Parameters

Param	Type	Description
`recipient`	`string`	Agent receiving funds on release
`amount`	`bigint`	Amount in wei
`deadline`	`number`	Unix timestamp — refund allowed after this
`options.memo`	`string`	Optional on-chain memo

Returns `EscrowResult`


{ escrowId: number, txHash: string }

Create ERC-20 Escrow

Requires token approval to the escrow contract first.


const WVRN = '0x1c17b46bd9b37024e86EA5fe05e1dE835aE1Ce0E'
 
// Approve the escrow contract (not the router)
await client.approveEscrow(WVRN, ethers.parseEther('100'))
 
const deadline = Math.floor(Date.now() / 1000) + 86400
 
const { escrowId } = await client.createEscrowERC20(
  recipientAddress,
  WVRN,
  ethers.parseEther('50'),
  deadline,
  { memo: 'data analysis task' }
)

Note: approveEscrow approves the EscrowRouter contract. This is separate from approveRouter which approves the PaymentRouter. Wait a few seconds after approval before creating the escrow.

Release

Only the sender can release. Transfers funds (minus 0.5% fee) to the recipient.


const hash = await client.releaseEscrow(escrowId)

Refund

Only the sender can refund, and only after the deadline has passed. No fee charged.


const hash = await client.refundEscrow(escrowId)

Query Escrow


const info = await client.getEscrow(escrowId)

Returns `EscrowInfo`


{
  escrowId: number
  sender: string        // Address that created the escrow
  recipient: string     // Address that receives on release
  token: string         // Token address (0x0 for ETH)
  amount: bigint        // Locked amount
  deadline: number      // Unix timestamp
  status: EscrowStatus  // Open (0), Released (1), Refunded (2)
}

EscrowStatus


import { EscrowStatus } from '@weavrn/sdk'
 
EscrowStatus.Open     // 0
EscrowStatus.Released // 1
EscrowStatus.Refunded // 2

Deadline Constraints

Minimum: 5 minutes from creation
Maximum: 365 days from creation
Refund only available after deadline passes