Sardis Escrow

Sardis Escrow - Smart Contract Payment Protection

Secure agent-to-agent payments with smart contract escrow. Funds held until delivery confirmation, protecting both buyer and seller in autonomous transactions.

Capabilities

• Create Escrow: Establish trustless payment agreements
• Fund Escrow: Deposit funds into smart contract custody
• Confirm Delivery: Seller confirms work/goods delivered
• Release Payment: Buyer releases funds after verification
• Escrow Status: Real-time escrow state tracking
• Dispute Resolution: Built-in arbitration for failed deliveries

Security Model

ESCROW-PROTECTED: Funds locked in smart contracts until both parties confirm. No centralized custody.

Quick Setup

export SARDIS_API_KEY=sk_your_key_here

API Endpoint Patterns

Base URL: https://api.sardis.sh/v2

Create Escrow

# Establish a new escrow agreement
curl -X POST https://api.sardis.sh/v2/escrow \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_wallet_id": "wallet_buyer123",
    "seller_wallet_id": "wallet_seller456",
    "amount": "500.00",
    "token": "USDC",
    "chain": "base",
    "description": "API development services - 40 hours",
    "delivery_deadline": "2026-03-01T00:00:00Z",
    "auto_release_after_hours": 72,
    "milestones": [
      {
        "description": "Phase 1: Design",
        "amount": "150.00",
        "deadline": "2026-02-25T00:00:00Z"
      },
      {
        "description": "Phase 2: Implementation",
        "amount": "250.00",
        "deadline": "2026-02-28T00:00:00Z"
      },
      {
        "description": "Phase 3: Testing & Deployment",
        "amount": "100.00",
        "deadline": "2026-03-01T00:00:00Z"
      }
    ]
  }'

# Example response:
# {
#   "escrow_id": "escrow_xyz789",
#   "contract_address": "0x1234567890abcdef...",
#   "status": "created",
#   "buyer": "wallet_buyer123",
#   "seller": "wallet_seller456",
#   "amount": "500.00",
#   "token": "USDC",
#   "chain": "base",
#   "funded": false,
#   "created_at": "2026-02-21T10:00:00Z"
# }

Fund Escrow

# Buyer deposits funds into escrow contract
curl -X POST https://api.sardis.sh/v2/escrow/{escrow_id}/fund \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "escrow_id": "escrow_xyz789",
    "wallet_id": "wallet_buyer123"
  }'

# Example:
curl -X POST https://api.sardis.sh/v2/escrow/escrow_xyz789/fund \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"escrow_id": "escrow_xyz789", "wallet_id": "wallet_buyer123"}'

Confirm Delivery

# Seller confirms delivery of goods/services
curl -X POST https://api.sardis.sh/v2/escrow/{escrow_id}/confirm-delivery \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "escrow_id": "escrow_xyz789",
    "wallet_id": "wallet_seller456",
    "delivery_proof": {
      "type": "github_pr",
      "url": "https://github.com/company/repo/pull/123",
      "commit_hash": "abc123def456",
      "notes": "All 3 milestones completed and tested"
    }
  }'

Release Escrow

# Buyer releases funds to seller after verification
curl -X POST https://api.sardis.sh/v2/escrow/{escrow_id}/release \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "escrow_id": "escrow_xyz789",
    "wallet_id": "wallet_buyer123",
    "amount": "500.00",
    "milestone_id": null,
    "rating": 5,
    "feedback": "Excellent work, delivered ahead of schedule"
  }'

# Partial release for milestone:
curl -X POST https://api.sardis.sh/v2/escrow/escrow_xyz789/release \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "escrow_id": "escrow_xyz789",
    "wallet_id": "wallet_buyer123",
    "amount": "150.00",
    "milestone_id": "milestone_1"
  }'

Get Escrow Status

# Query current escrow state and transaction history
curl -X GET https://api.sardis.sh/v2/escrow/{escrow_id} \
  -H "Authorization: Bearer $SARDIS_API_KEY"

# Example:
curl -X GET https://api.sardis.sh/v2/escrow/escrow_xyz789 \
  -H "Authorization: Bearer $SARDIS_API_KEY"

Example Commands

Complete Escrow Workflow

# 1. Create escrow agreement
ESCROW=$(curl -s -X POST https://api.sardis.sh/v2/escrow \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_wallet_id": "wallet_buyer123",
    "seller_wallet_id": "wallet_seller456",
    "amount": "500.00",
    "token": "USDC",
    "chain": "base",
    "description": "Development work"
  }')

ESCROW_ID=$(echo "$ESCROW" | jq -r '.escrow_id')
echo "Created escrow: $ESCROW_ID"

# 2. Buyer funds the escrow
echo "Funding escrow..."
curl -X POST "https://api.sardis.sh/v2/escrow/$ESCROW_ID/fund" \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"escrow_id\": \"$ESCROW_ID\", \"wallet_id\": \"wallet_buyer123\"}"

# 3. Wait for seller delivery (automated)
echo "Waiting for delivery confirmation..."

# 4. Seller confirms delivery
curl -X POST "https://api.sardis.sh/v2/escrow/$ESCROW_ID/confirm-delivery" \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"escrow_id\": \"$ESCROW_ID\", \"wallet_id\": \"wallet_seller456\"}"

# 5. Buyer verifies and releases
echo "Releasing payment to seller..."
curl -X POST "https://api.sardis.sh/v2/escrow/$ESCROW_ID/release" \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"escrow_id\": \"$ESCROW_ID\",
    \"wallet_id\": \"wallet_buyer123\",
    \"amount\": \"500.00\",
    \"rating\": 5
  }"

echo "Escrow completed!"

Monitor Escrow Status

# Track escrow progress
ESCROW_ID=escrow_xyz789

while true; do
  STATUS=$(curl -s -X GET "https://api.sardis.sh/v2/escrow/$ESCROW_ID" \
    -H "Authorization: Bearer $SARDIS_API_KEY")

  STATE=$(echo "$STATUS" | jq -r '.status')
  FUNDED=$(echo "$STATUS" | jq -r '.funded')
  DELIVERED=$(echo "$STATUS" | jq -r '.delivery_confirmed')

  echo "=== Escrow Status ==="
  echo "State: $STATE"
  echo "Funded: $FUNDED"
  echo "Delivery Confirmed: $DELIVERED"

  if [[ "$STATE" == "completed" || "$STATE" == "refunded" ]]; then
    echo "Escrow finalized: $STATE"
    break
  fi

  sleep 30
done

List Active Escrows

# Get all escrows for a wallet
WALLET_ID=wallet_buyer123

curl -s -X GET "https://api.sardis.sh/v2/escrow?wallet_id=$WALLET_ID&status=active" \
  -H "Authorization: Bearer $SARDIS_API_KEY" | \
  jq -r '.escrows[] | "\(.escrow_id): \(.description) - \(.amount) \(.token) [\(.status)]"'

Milestone-Based Release

# Release funds incrementally as milestones complete
ESCROW_ID=escrow_xyz789

# Release milestone 1
curl -X POST "https://api.sardis.sh/v2/escrow/$ESCROW_ID/release" \
  -H "Authorization: Bearer $SARDIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "escrow_id": "'"$ESCROW_ID"'",
    "wallet_id": "wallet_buyer123",
    "amount": "150.00",
    "milestone_id": "milestone_1",
    "feedback": "Phase 1 design approved"
  }'

echo "Milestone 1 payment released"

Response Examples

Create Escrow Response

{
  "escrow_id": "escrow_xyz789",
  "contract_address": "0x1234567890abcdef1234567890abcdef12345678",
  "status": "created",
  "buyer": "wallet_buyer123",
  "seller": "wallet_seller456",
  "amount": "500.00",
  "token": "USDC",
  "chain": "base",
  "description": "API development services - 40 hours",
  "delivery_deadline": "2026-03-01T00:00:00Z",
  "auto_release_after_hours": 72,
  "milestones": [
    {
      "milestone_id": "milestone_1",
      "description": "Phase 1: Design",
      "amount": "150.00",
      "deadline": "2026-02-25T00:00:00Z",
      "status": "pending"
    },
    {
      "milestone_id": "milestone_2",
      "description": "Phase 2: Implementation",
      "amount": "250.00",
      "deadline": "2026-02-28T00:00:00Z",
      "status": "pending"
    },
    {
      "milestone_id": "milestone_3",
      "description": "Phase 3: Testing & Deployment",
      "amount": "100.00",
      "deadline": "2026-03-01T00:00:00Z",
      "status": "pending"
    }
  ],
  "funded": false,
  "delivery_confirmed": false,
  "created_at": "2026-02-21T10:00:00Z"
}

Escrow Status Response

{
  "escrow_id": "escrow_xyz789",
  "contract_address": "0x1234567890abcdef1234567890abcdef12345678",
  "status": "funded",
  "buyer": {
    "wallet_id": "wallet_buyer123",
    "agent_id": "agent_buyer"
  },
  "seller": {
    "wallet_id": "wallet_seller456",
    "agent_id": "agent_seller"
  },
  "amount": "500.00",
  "token": "USDC",
  "chain": "base",
  "description": "API development services - 40 hours",
  "funded": true,
  "funded_at": "2026-02-21T10:30:00Z",
  "funded_tx_hash": "0xabcdef123456...",
  "delivery_confirmed": false,
  "delivery_confirmed_at": null,
  "released_amount": "0.00",
  "remaining_amount": "500.00",
  "milestones": [
    {
      "milestone_id": "milestone_1",
      "description": "Phase 1: Design",
      "amount": "150.00",
      "deadline": "2026-02-25T00:00:00Z",
      "status": "pending",
      "released": false
    }
  ],
  "timeline": [
    {
      "event": "created",
      "timestamp": "2026-02-21T10:00:00Z"
    },
    {
      "event": "funded",
      "timestamp": "2026-02-21T10:30:00Z",
      "tx_hash": "0xabcdef123456..."
    }
  ],
  "auto_release_at": "2026-03-04T10:30:00Z",
  "created_at": "2026-02-21T10:00:00Z"
}

Release Response

{
  "escrow_id": "escrow_xyz789",
  "status": "completed",
  "released_amount": "500.00",
  "token": "USDC",
  "recipient": "wallet_seller456",
  "tx_hash": "0x9876543210fedcba9876543210fedcba98765432",
  "rating": 5,
  "feedback": "Excellent work, delivered ahead of schedule",
  "released_at": "2026-02-28T14:00:00Z",
  "contract_address": "0x1234567890abcdef1234567890abcdef12345678",
  "message": "Escrow released successfully. Funds transferred to seller."
}

Error Handling

• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Not authorized to interact with this escrow
• 404 Not Found - Escrow not found
• 409 Conflict - Escrow already funded/released
• 400 Bad Request - Invalid escrow parameters or insufficient funds
• 422 Unprocessable Entity - Deadline passed or milestone not met

Use Cases

• Agent-to-Agent Hiring: Secure payments for AI agent services
• API Integrations: Pay for third-party API development
• Content Creation: Escrow for commissioned content work
• Data Processing: Pay for dataset processing/labeling
• Bounty Programs: Hold funds for completed tasks

Related Skills

• sardis-payment - Direct payments without escrow
• sardis-identity - Verify agent identities before escrow
• sardis-balance - Check wallet balances for funding

Links

• Website: https://sardis.sh
• Documentation: https://sardis.sh/docs/escrow
• Smart Contracts: https://github.com/sardis-sh/contracts
• API Reference: https://api.sardis.sh/v2/docs
• Support: support@sardis.sh