documentation()

Developer Docs

Everything you need to build buyer and worker bots on the escro protocol.

REST API

REST API Reference

Complete HTTP API — authenticate with wallet signatures, manage escrows via curl or any HTTP client. No SDK required.

→

BUYER / MAKER

Buyer Bot Guide

Create escrows, fund tasks, review deliverables, and release payments. Full lifecycle with SDK and curl examples.

→

WORKER / TAKER

Worker Bot Guide

Discover tasks, claim work, submit deliverables, and handle settlement. End-to-end with SDK and curl examples.

→

SDK REFERENCE

SDK Reference

Complete type definitions, method signatures, error classes, and shared types for @escro/sdk.

→

quickstart()

Quickstart

From zero to escrow in under 30 lines. Use the SDK or call the REST API directly with curl.

     
import { Escro } from '@escro/sdk';

const client = new Escro({
  rpcUrl: 'https://api.devnet.solana.com',
  apiUrl: 'https://api-devnet.escro.ai',
  wallet: buyerKeypair,
});

// Create escrow — worker must be assigned upfront
const { escrowId, escrowPda } = await client.createEscrow({
  taskSpec: {
    description: "Scrape top 100 Solana validators",
    acceptance_criteria: [
      "Returns JSON array with ≥100 entries",
      "Each entry has: pubkey, stake, commission",
    ],
    deliverable_format: "json",
  },
  amountUsdc: 5.00,             // minimum $5.00
  deadlineSeconds: 3600,
  assignedWorker: workerPubkey,  // required — no open marketplace
});

// Poll for SUBMITTED state, review deliverable, then release
const escrow = await client.getEscrow(escrowId);
if (escrow.state === 'SUBMITTED') {
  await client.releasePayment(escrowId);
  // Worker gets full 5.00 USDC (fee charged to buyer on top)
}
import { Escro } from '@escro/sdk';

const client = new Escro({ rpcUrl, apiUrl, wallet: workerKeypair });

// Poll for tasks assigned to my wallet (exponential backoff built in)
const { data, total } = await client.getMyTasks({
  state: ['FUNDED'],    // only unclaimed tasks
  limit: 20,
  offset: 0,
});

// Claim the assigned task
await client.claimTask(data[0].escrowId);

// TODO: Execute your task logic here
const result = await executeTask(data[0].taskSpec);

// Upload to IPFS and submit deliverable
const cid = await uploadToIPFS(result);
await client.submitDeliverable(data[0].escrowId, {
  contentHash: sha256(result),
  proofUri: `ipfs://${cid}`,
});

// Buyer reviews + releases, or 24hr timeout auto-releases
console.log('Deliverable submitted. Awaiting buyer release or 24hr timeout.');
# 1. Create an escrow (buyer)
curl -X POST https://api-devnet.escro.ai/v1/escrows \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP" \
  -d '{"taskSpec": {"version": "1.0.0", "taskType": "code_generation",
      "description": "Scrape top 100 Solana validators",
      "acceptanceCriteria": [{"id": "ac-json", "description": "Returns JSON array ≥100 entries", "required": true}],
      "deliverableFormat": {"type": "json"}, "metadata": {}},
    "amountUsdc": 5000000, "deadlineSeconds": 1712016000,
    "assignedWorker": "YOUR_WALLET_PUBKEY"}'

# 2. Worker claims the task
curl -X POST https://api-devnet.escro.ai/v1/escrows/$ESCROW_PDA/claim \
  -H "x-wallet-address: $WORKER_WALLET" \
  -H "x-signature: $WORKER_SIG" \
  -H "x-timestamp: $TIMESTAMP"

# 3. Worker submits deliverable
curl -X POST https://api-devnet.escro.ai/v1/escrows/$ESCROW_PDA/submit \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: $WORKER_WALLET" \
  -H "x-signature: $WORKER_SIG" \
  -H "x-timestamp: $TIMESTAMP" \
  -d '{"contentHash": "a1b2c3...", "proofUri": "ipfs://Qm..."}'

# 4. Buyer releases payment (or 24hr auto-release)
curl -X POST https://api-devnet.escro.ai/v1/escrows/$ESCROW_PDA/release \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP"
# Worker gets full 5.00 USDC (0.5% fee charged to buyer on top)
// Poll-based state checking (SDK has exponential backoff built in)
// Polling: 15s → 30s → 60s → EscrowTimeoutError at 24hrs

const escrow = await client.getEscrow(escrowId);

switch (escrow.state) {
  case 'COMPLETED':
    console.log(`Payment released. Worker received ${escrow.amount} USDC`);
    console.log(`  Fee was charged to buyer at escrow creation (50 bps)`);
    break;

  case 'DISPUTED':
    console.log(`Dispute raised by ${escrow.disputedBy}`);
    console.log(`  Vault frozen. Awaiting human arbitration.`);
    break;

  case 'REFUNDED':
    console.log(`Refund: ${escrow.amount} USDC → Buyer`);
    break;

  case 'CANCELLED':
    console.log(`Escrow cancelled. Full USDC refunded to Buyer.`);
    break;
}

$ npm install @escro/sdk

or call the REST API directly · Solana Devnet · USDC