Skip to main content
POST
/
v1
/
participants
/
{id}
/
balances
/
hold
Hold participant balance
curl --request POST \
  --url https://api.scrip.dev/v1/participants/{id}/balances/hold \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "description": "Hold for pending order #123",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "bucket": "AVAILABLE",
  "earned_from": "2024-01-01T00:00:00Z",
  "earned_to": "2024-12-31T23:59:59Z",
  "idempotency_key": "order-123-hold",
  "lot_ids": [
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "reference_id": "auth_12345"
}
'
{
  "amount_processed": "100.00",
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "balance": {
    "available": "1400.00",
    "deferred": "0.00",
    "held": "200.00"
  },
  "journal_entry_id": "550e8400-e29b-41d4-a716-446655440003",
  "lots_processed": [
    {
      "amount": "50.00",
      "id": "550e8400-e29b-41d4-a716-446655440002"
    }
  ],
  "message": "Processed 100.00",
  "operation": "HOLD",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "auth_12345"
}
Moves funds from AVAILABLE to HELD for a participant. Held funds are not spendable and remain reserved until explicitly released or forfeited. Common use cases include authorization holds, fraud review, and pending approval workflows. For assets in LOT mode, hold operations preserve lot-level metadata such as expires_at and matures_at. The hold will fail if the participant does not have sufficient AVAILABLE balance.

​
Hold/Release Correlation (reference_id)

For LOT mode assets, you can include an optional reference_id to correlate this hold with a future release. Held lots are stamped with the reference, and a subsequent release using the same reference_id will target only those lots. This is useful when a participant has multiple concurrent holds (e.g., multiple pending orders).
  • Format: 1-255 characters, alphanumeric plus ._:@-
  • Only supported on LOT mode assets
  • Not supported for forfeit operations
  • The reference_id is visible on lot responses and journal entries
For usage patterns and examples, see the Balance Operations guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

​
id
string<uuid>
required

Participant ID

Body

application/json

Hold operation details

​
asset_id
string<uuid>
required

Asset to operate on

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
description
string
required

Reason for this operation

Required string length: 1 - 500
Example:

"Hold for pending order #123"

​
program_id
string<uuid>
required

Program this operation belongs to

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
amount
string

Amount to process. Omit to process the full balance (SIMPLE) or all matching lots (LOT)

Example:

"100.00"

​
bucket
enum<string>

Which bucket to forfeit from. Required for forfeit; ignored for hold/release

Available options:
AVAILABLE,
HELD
Example:

"AVAILABLE"

​
earned_from
string<date-time>

Only process lots earned on or after this time (RFC 3339). LOT mode only.

Example:

"2024-01-01T00:00:00Z"

​
earned_to
string<date-time>

Only process lots earned on or before this time (RFC 3339). LOT mode only. Must be >= earned_from when both are provided.

Example:

"2024-12-31T23:59:59Z"

​
idempotency_key
string

Client-provided key to prevent duplicate operations on retry

Example:

"order-123-hold"

​
lot_ids
string[]

Restrict to specific lots. LOT mode only

Example:
["550e8400-e29b-41d4-a716-446655440002"]
​
reference_id
string

Correlation ID linking holds to releases. LOT mode only. Hold stamps lots; release filters by reference.

Example:

"auth_12345"

Response

Hold processed

​
amount_processed
string

Total amount processed

Example:

"100.00"

​
asset_id
string<uuid>

Asset ID

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
balance
object

Balance after the operation

​
journal_entry_id
string<uuid>

Ledger journal entry created by this operation

Example:

"550e8400-e29b-41d4-a716-446655440003"

​
lots_processed
object[]

Individual lots affected. Only present for LOT mode assets

​
message
string

Confirmation message

Example:

"Processed 100.00"

​
operation
string

Operation performed

Example:

"HOLD"

​
program_id
string<uuid>

Program ID

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
reference_id
string

Correlation ID linking this hold/release (if provided)

Example:

"auth_12345"