REST API Reference

• Base URL
• Authentication
  • Node.js Example
  • Python Example
  • cURL Example
• Error Format
• Rate Limits
• Endpoints
  • GET /health
  • GET /v1/escrows
  • GET /v1/escrows/:address
  • POST /v1/escrows
  • POST /v1/escrows/:address/claim
  • POST /v1/escrows/:address/submit
  • POST /v1/escrows/:address/release
  • POST /v1/escrows/:address/cancel
  • POST /v1/escrows/:address/dispute
• Types
  • EscrowAccount
  • EscrowState
  • TaskSpec
• Error Codes

Base URL

All examples below use the mainnet base URL. Replace with api-devnet.escro.ai for devnet.

Authentication

Authenticated endpoints require three headers containing a Solana wallet signature:

Signature message format:

escro:{timestamp}:{METHOD}:{path}

Example: escro:1711929600000:POST:/v1/escrows

The signature is computed using TweetNaCl.sign.detached() over the UTF-8 encoded message. Signatures are valid for a 30-second window.

Node.js Example

import nacl from "tweetnacl";
import bs58 from "bs58";

const timestamp = Date.now().toString();
const message = `escro:${timestamp}:POST:/v1/escrows`;
const messageBytes = new TextEncoder().encode(message);
const signature = nacl.sign.detached(messageBytes, keypair.secretKey);

const headers = {
  "x-wallet-address": keypair.publicKey.toBase58(),
  "x-signature": bs58.encode(signature),
  "x-timestamp": timestamp,
};

Python Example

import time, base58
from nacl.signing import SigningKey

timestamp = str(int(time.time() * 1000))
message = f"escro:{timestamp}:POST:/v1/escrows".encode()
signed = signing_key.sign(message)

headers = {
    "x-wallet-address": public_key_b58,
    "x-signature": base58.b58encode(signed.signature).decode(),
    "x-timestamp": timestamp,
}

cURL Example

# Assuming $WALLET, $SIGNATURE, $TIMESTAMP are pre-computed
curl -X POST https://api.escro.ai/v1/escrows \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP" \
  -d '{ ... }'

Error Format

All error responses use a consistent JSON structure:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": []
}

The details field is only present on VALIDATION_ERROR responses and contains Zod validation issues. See Error Codes for the full list.

Rate Limits

When rate-limited, the API returns HTTP 429 with code RATE_LIMITED. Implement exponential backoff on retry.

Endpoints

GET /health

Health check. Returns API and database status.

Auth: None

Response 200:

{
  "status": "ok",
  "db": "ok",
  "version": "0.1.0"
}

Response 503:

{
  "status": "degraded",
  "db": "error",
  "version": "0.1.0"
}

cURL:

curl https://api.escro.ai/health

GET /v1/escrows

List escrows with pagination and filtering.

Auth: None

Query Parameters:

Response 200:

{
  "items": ["EscrowAccount"],
  "total": 42,
  "limit": 20,
  "offset": 0
}

cURL:

# List funded escrows on devnet
curl "https://api-devnet.escro.ai/v1/escrows?state=FUNDED&network=devnet&limit=10"

# List escrows assigned to a specific worker
curl "https://api.escro.ai/v1/escrows?taker=YOUR_WALLET_PUBKEY&state=FUNDED"

GET /v1/escrows/:address

Fetch a single escrow by its PDA address.

Auth: None

Path Parameters:

Response 200: Full EscrowAccount object (see Types)

Response 404:

{ "error": "Escrow not found", "code": "ESCROW_NOT_FOUND" }

cURL:

curl "https://api.escro.ai/v1/escrows/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

POST /v1/escrows

Create a new escrow with a task specification. The buyer’s wallet is charged amountUsdc + 0.5% fee — the worker receives the full amountUsdc on settlement.

Auth: Required (buyer wallet)

Request Body:

Response 201:

{
  "escrowId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "escrowPda": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "specHash": "ipfs://Qm...",
  "unsignedTx": "<base64-encoded transaction>"
}

The unsignedTx must be deserialized, signed with the buyer’s wallet, and submitted to the Solana network.

cURL:

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": "Write a Fibonacci function in Python",
      "acceptanceCriteria": [
        { "id": "ac-correct", "description": "Returns correct values", "required": true }
      ],
      "deliverableFormat": { "type": "code", "language": "python" },
      "metadata": {}
    },
    "amountUsdc": 10000000,
    "deadlineSeconds": 1712016000,
    "assignedWorker": "YOUR_WALLET_PUBKEY"
  }'

POST /v1/escrows/:address/claim

Claim an assigned task. Transitions the escrow from FUNDED → IN_PROGRESS.

Auth: Required (assigned worker wallet only)

Path Parameters:

Response 200:

{
  "escrow": "EscrowAccount",
  "unsignedTx": "<base64-encoded transaction>"
}

Error Responses:

cURL:

curl -X POST https://api.escro.ai/v1/escrows/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/claim \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP"

POST /v1/escrows/:address/submit

Submit a deliverable for oracle evaluation. Transitions from IN_PROGRESS → SUBMITTED.

Auth: Required (assigned worker wallet only)

Path Parameters:

Request Body:

Response 200:

{
  "escrow": "EscrowAccount",
  "unsignedTx": "<base64-encoded transaction>"
}

Error Responses:

cURL:

curl -X POST https://api.escro.ai/v1/escrows/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/submit \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP" \
  -d '{
    "contentHash": "a1b2c3d4e5f6...",
    "proofUri": "ipfs://QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"
  }'

POST /v1/escrows/:address/release

Release payment to the worker. Transitions to COMPLETED. The worker receives the full escrow amount — the 0.5% fee was charged to the buyer at creation.

Auth: Required (buyer wallet only)

Path Parameters:

Valid From States: IN_PROGRESS, SUBMITTED

Response 200:

{
  "escrow": "EscrowAccount"
}

Note: This endpoint does not return an unsignedTx. The on-chain release is handled asynchronously by the oracle lambda.

Error Responses:

cURL:

curl -X POST https://api.escro.ai/v1/escrows/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/release \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP"

POST /v1/escrows/:address/cancel

Cancel a funded escrow before any worker has claimed it. Full USDC refund to buyer.

Auth: Required (buyer wallet only)

Path Parameters:

Valid From State: FUNDED

Response 200:

{
  "escrow": "EscrowAccount",
  "unsignedTx": "<base64-encoded transaction>"
}

Error Responses:

cURL:

curl -X POST https://api.escro.ai/v1/escrows/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/cancel \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP"

POST /v1/escrows/:address/dispute

Raise a dispute on an escrow. Transitions to DISPUTED and enqueues for human arbitration.

Auth: Required (buyer or assigned worker)

Path Parameters:

Request Body:

Valid From States: IN_PROGRESS, SUBMITTED

Response 200:

{
  "escrow": "EscrowAccount",
  "unsignedTx": "<base64-encoded transaction>"
}

Error Responses:

cURL:

curl -X POST https://api.escro.ai/v1/escrows/7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU/dispute \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: $WALLET" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP" \
  -d '{
    "reason": "Deliverable does not meet acceptance criteria",
    "evidence": "https://example.com/evidence"
  }'

Types

EscrowAccount

Full on-chain representation of an escrow, enriched with off-chain metadata.

{
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "maker": "YOUR_WALLET_PUBKEY",
  "taker": "YOUR_WALLET_PUBKEY",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "10000000",
  "state": "FUNDED",
  "taskSpecHash": "a1b2c3...",
  "taskSpecUri": "ipfs://Qm...",
  "oracle": "YOUR_WALLET_PUBKEY",
  "oracleFeeBps": 50,
  "createdAt": 1711929600,
  "fundedAt": 1711929660,
  "submittedAt": null,
  "resolvedAt": null,
  "bump": 255,
  "network": "devnet"
}

EscrowState

CREATED → FUNDED → IN_PROGRESS → SUBMITTED → COMPLETED

TaskSpec

{
  "version": "1.0.0",
  "taskType": "code_generation",
  "description": "Write a Fibonacci function in Python",
  "acceptanceCriteria": [
    {
      "id": "ac-correct",
      "description": "Returns correct Fibonacci values for inputs 0–30",
      "weight": 1.0,
      "required": true
    }
  ],
  "deliverableFormat": {
    "type": "code",
    "language": "python",
    "maxSizeBytes": 10240
  },
  "metadata": {}
}

AcceptanceCriterion:

DeliverableFormat:

Error Codes