Skip to main content
POST
/
v1
/
settle
curl -X POST https://facilitator.api.0xmeta.ai/v1/settle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "Idempotency-Key: settle_$(date +%s)" \
  -d '{
    "verification_id": "ver_abc123def456",
    "destination_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
    "amount": null,
    "metadata": {
      "payout_id": "PAYOUT-789"
    }
  }'

{
  "settlement_id": "set_xyz789ghi012",
  "verification_id": "ver_abc123def456",
  "status": "pending",
  "settlement_tx_hash": null,
  "settled_amount": null,
  "settled_at": null,
  "details": {
    "estimated_time": 300
  }
}

​
Endpoint

Initiate settlement to transfer verified funds to a destination address.
​
verification_id
string
required
The verification ID from a successful payment verification Example: ver_abc123def456
​
destination_address
string
required
Blockchain address to receive the funds (42 characters, must start with 0x) Example: 0x742d35cc6634c0532925a3b844bc9e7595f0beb0
​
amount
string
Amount to settle in wei. If null, settles the full verified amount. Example: "500000000000000000" (0.5 ETH)
​
metadata
object
Additional metadata for the settlement
{
  "payout_id": "PAYOUT-789",
  "notes": "Monthly payout"
}

​
Headers

​
X-API-Key
string
required
Your API key for authentication
​
Idempotency-Key
string
Unique key to prevent duplicate settlements. Valid for 24 hours.
curl -X POST https://facilitator.api.0xmeta.ai/v1/settle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "Idempotency-Key: settle_$(date +%s)" \
  -d '{
    "verification_id": "ver_abc123def456",
    "destination_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb0",
    "amount": null,
    "metadata": {
      "payout_id": "PAYOUT-789"
    }
  }'

{
  "settlement_id": "set_xyz789ghi012",
  "verification_id": "ver_abc123def456",
  "status": "pending",
  "settlement_tx_hash": null,
  "settled_amount": null,
  "settled_at": null,
  "details": {
    "estimated_time": 300
  }
}

​
Response Fields

​
settlement_id
string
required
Unique identifier for this settlement
​
verification_id
string
required
The associated verification ID
​
status
string
required
Settlement status: pending, settled, failed, or rejected
​
settlement_tx_hash
string
Transaction hash of the settlement (available when settled)
​
settled_amount
string
Amount settled in wei (available when settled)
​
settled_at
string
ISO 8601 timestamp when settlement completed
​
details
object
Additional settlement details (fees, gas, estimated time)

​
Settlement Process

1

Initiate Settlement

Call the settle endpoint with verification_id
2

Background Processing

Settlement is processed asynchronously by background workers
3

Automatic Polling

Status is automatically polled every 5 seconds
4

Webhook Notification

You receive a webhook when settlement completes (if webhook_url was provided during verification)

​
Settlement States

{
  "verification_id": "ver_abc123",
  "destination_address": "0x...",
  "amount": null  // Settles full verified amount
}

{
  "verification_id": "ver_abc123",
  "destination_address": "0x...",
  "amount": "500000000000000000"  // Settle 0.5 ETH
}

{
  "verification_id": "ver_abc123",
  "destination_address": "0x...",
  "metadata": {
    "payout_batch": "2025-01-15",
    "recipient_id": "USER-123"
  }
}
Settlement typically completes in 1-5 minutes depending on network congestion.
Only verified payments can be settled. The verification status must be verified.
Use webhooks to get notified when settlement completes instead of polling.