Create a settlement
Execution support pending. Check applicability.
Object and complete fields · Authentication, amounts and errors · Integration guide
POST /v1/settlements
Submit item IDs. The platform determines amount, network, stablecoin and destination; do not supply them.
Select 1–100 distinct available items that can be collected to the same wallet in one transaction. Same network, stablecoin and wallet are necessary but do not guarantee every combination is compatible. settlement_items_incompatible requires reducing or changing the selection.
If any item is missing, unavailable or incompatible, the entire request is rejected without creating a task or reserving any items. Successful creation immediately marks all selected items in_progress.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique operation key; retain for retries |
item_ids | body | string[] | Yes | 1–100 distinct item identifiers |
After a timeout or unknown creation outcome, retry the original key and parameters. Valid replay returns the first creation result with the same task ID. Retrieve the task for current state.
Request:
POST /v1/settlements
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"item_ids": ["si_example"]
}
Response: 200 OK, complete Settlement in preparing:
{
"id": "st_example",
"status": "preparing",
"item_ids": ["si_example"],
"amount": "12.5",
"currency": "usdc",
"chain": 8453,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678",
"next_action": null,
"transaction_hash": null,
"last_execution_error": null,
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:00:00Z",
"settled_at": null
}