Valta Docs

Escrow API

See Escrow for the state machine (pending → funded → released | disputed) and the release-vs-dispute exclusivity guarantee this API implements.

All four calls require authentication — an API key (x-api-key: vlt_live_...) or a logged-in dashboard session — and all accept the same Idempotency-Key header described in Payout Intents.

POST /escrow/create

Opens a pending escrow. No funds move.

Field	Required	Description
`fromWalletId`	yes	The `bot_wallet` id funds will be debited from. You must own this wallet.
`toWalletId`	yes	The `bot_wallet` id funds will be credited to on release.
`amount`	yes	Amount, in the wallet's currency.
`conditions`	no	Free-form JSON describing release conditions (not enforced by Valta — informational).

bash

curl https://valta.co/api/v1/escrow/create \
  -H 'x-api-key: vlt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"fromWalletId": 42, "toWalletId": 91, "amount": 500}'

json

{
  "success": true,
  "escrow": { "id": 7, "fromWalletId": 42, "toWalletId": 91, "amount": 500, "status": "pending", "conditions": {} }
}

POST /escrow/fund

pending → funded. Debits fromWalletId. Requires the caller to own the source wallet.

bash

curl https://valta.co/api/v1/escrow/fund \
  -H 'x-api-key: vlt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"escrowId": 7}'

json

{ "success": true, "escrowId": 7, "status": "funded", "intentId": "int_..." }

POST /escrow/release

funded → released. Credits toWalletId. Either party to the escrow may call this.

bash

curl https://valta.co/api/v1/escrow/release \
  -H 'x-api-key: vlt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"escrowId": 7}'

POST /escrow/dispute

funded → disputed. No funds move. Either party may call this.

Field	Required	Description
`escrowId`	yes
`reason`	no	Recorded as `dispute_reason` on the escrow.

bash

curl https://valta.co/api/v1/escrow/dispute \
  -H 'x-api-key: vlt_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"escrowId": 7, "reason": "Delivery not received"}'

Errors

Status	Meaning
`401`	Missing or invalid auth.
`403`	Authenticated, but either not a party to the wallet(s)/escrow involved, or your workspace role doesn't allow it — `create`/`fund` need Owner or Admin (`wallet.fund_agent`), `release`/`dispute` need Manager and above (`wallet.move`). Viewers can't call any of these.
`404`	Escrow or wallet not found.
`400`	Wrong state for this call (e.g. releasing a `pending`, not-yet-funded escrow), or insufficient balance to fund.
`409`	The escrow was already resolved — either a genuine dedup replay (`"replayed": true` in the body), or it lost a real release-vs-dispute race (see Escrow).

SDK equivalent

Not yet built. Use the curl calls above directly until packages/valta-sdk adds an escrow resource.