Try to release a settlement now

POST/v1/settlements/{id}/release

Asks the settlement engine to plan this network again: a held settlement is released if the master wallet can now pay for it, a failed one is retried. The answer is the settlement as it is now; settlement.released or settlement.held follows by webhook.

Authorization

Send your API key as a bearer token in the Authorization header. Secret API key: Authorization: Bearer ctp_live_sk_…. A publishable key (ctp_…_pk_…) is accepted by these operations only, which serve reference data: getRate, listAssets, listNetworks (each marked x-publishable-key: true). Every other operation refuses it with 403 publishable_key_not_allowed, whatever Origin the request carries: that header binds browsers, not other clients, and nothing on this API relies on it.

Path parameters

Name	Type	Description
id required	string	At most 100 characters.

Headers

Name	Type	Description
Idempotency-Key	string	Makes the request safe to retry: the same key with the same request replays the first response (Idempotent-Replayed: true) for 24 hours; the same key with a different request is 422 idempotency_key_reused; while the first request is still running, 409 idempotency_request_in_progress with Retry-After. Only POST honours it. At most 255 characters. Pattern ^[!-~]+$.

Example request

cURL

curl -X POST "https://api.ctpeway.com/v1/settlements/{id}/release" \
  -H "Authorization: Bearer $CTPEWAY_API_KEY" \
  -H "Idempotency-Key: <a-unique-key>"

Node SDK

import { CtpeWay } from '@ctpeway/sdk';

const ctpeway = new CtpeWay(process.env.CTPEWAY_API_KEY);

const result = await ctpeway.settlements.release('<id>');

Response

200 OK

Field	Type	Description
id	string
status	string	One of pending, held, releasing, released, failed, reverted.
payment_id	string
invoice_id optional	string
deposit_address_id optional	string
network	string
asset	string
asset_id	string
native_asset	string
gross	string	The deposit, base units of asset. A whole number written as a string of digits.
usd_value	string	A decimal number written as a string, with up to 8 decimal places.
fee_bps	integer
fee_native	string	Platform fee owed, base units of native_asset. A whole number written as a string of digits.
fee_source	string	One of deposit, master.
fee_paid	string	A whole number written as a string of digits.
fee_carried	string	A whole number written as a string of digits.
required_native optional	string	Native coin the master wallet must hold for this release. A whole number written as a string of digits.
master_wallet_address optional	string
reason optional	string	Why it is held (status held) or why it failed (status failed); absent in any other status. insufficient_master_balance: Held: the master wallet has too little native coin to pay the platform fee and the network costs of the release (token deposits). Released by itself once the wallet is topped up. uneconomic: Held: the network fee of the release is estimated at more than half of what the deposit is worth. Looked at again on every planning run and released when the estimate falls. below_sweep_min: Held: the deposit is worth less than the merchant’s minimum for a sweep. It stays in its address until that setting allows it or another release from the same address takes it along. payment_orphaned: Failed: a chain reorganisation removed the payment while its release was under way. The settlement returns to the queue by itself if the payment confirms again. funds_missing: Failed: the deposit is no longer at its address and no release on record moved it. Needs an operator. not_releasable: Failed: the network cannot release this deposit as it stands (an asset or address it does not support, or a release plan that did not pass its checks). Needs an operator. transaction_failed: Failed: a transaction of the release was rejected or can no longer be included. Retried by an operator; what was already paid is not paid again. replanning: Failed for a moment: a transaction prepared for the release could not be used as it was, and the release is being planned again by itself. Nothing to do. unclassified: Failed: for a reason outside this list. Needs an operator. One of insufficient_master_balance, uneconomic, below_sweep_min, payment_orphaned, funds_missing, not_releasable, transaction_failed, replanning, unclassified.
fee_tx optional	string
topup_tx optional	string
sweep_tx optional	string
network_fees	string	A whole number written as a string of digits.
net_released optional	string	A whole number written as a string of digits.
simulated	boolean
confirmed_at	string (date-time)
held_since optional	string (date-time)
released_at optional	string (date-time)
failed_at optional	string (date-time)
fee_usd	string	The platform fee in USD, fixed when the payment confirmed. A decimal number written as a string, with up to 8 decimal places.
native_price	string	USD price of one whole native_asset in the price snapshot the fee was computed from: fee_native is fee_usd at this price. A decimal number written as a string, with up to 8 decimal places.
livemode	boolean	false for objects of the test environment.

{
  "id": "string",
  "status": "pending",
  "payment_id": "string",
  "invoice_id": "string",
  "deposit_address_id": "string",
  "network": "string",
  "asset": "string",
  "asset_id": "string",
  "native_asset": "string",
  "gross": "1000000",
  "usd_value": "10.00",
  "fee_bps": 0,
  "fee_native": "1000000",
  "fee_source": "deposit",
  "fee_paid": "1000000",
  "fee_carried": "1000000",
  "required_native": "1000000",
  "master_wallet_address": "string",
  "reason": "insufficient_master_balance",
  "fee_tx": "string",
  "topup_tx": "string",
  "sweep_tx": "string",
  "network_fees": "1000000",
  "net_released": "1000000",
  "simulated": true,
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "held_since": "2026-01-01T00:00:00.000Z",
  "released_at": "2026-01-01T00:00:00.000Z",
  "failed_at": "2026-01-01T00:00:00.000Z",
  "fee_usd": "10.00",
  "native_price": "10.00",
  "livemode": true
}

The values are placeholders generated from the schema. They show the shape, not real data.

Errors

A failed request answers with the error format described under Errors.

Besides the codes any endpoint can return, this endpoint can answer with these code values:

• settlement_not_found
• settlement_reverted