Skip to main content
POST
/
v1
/
transfers
Create a transfer
curl --request POST \
  --url https://api.scrip.dev/v1/transfers \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "description": "Monthly bonus distribution",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "recipients": [
    {
      "amount": "100.00",
      "external_id": "user_456",
      "group_id": "550e8400-e29b-41d4-a716-446655440005",
      "participant_id": "<string>"
    }
  ],
  "idempotency_key": "txn_abc123",
  "source_external_id": "user_123",
  "source_group_id": "550e8400-e29b-41d4-a716-446655440004",
  "source_participant_id": "<string>"
}
'
{
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "journal_entry_id": "550e8400-e29b-41d4-a716-446655440002",
  "recipient_count": 5,
  "source_id": "550e8400-e29b-41d4-a716-446655440003",
  "total_amount": "500.00"
}
Moves funds from one participant or group to one or more recipients. The operation is zero-sum: the source’s AVAILABLE balance is debited by the exact total credited across all recipients. You can include up to 100 recipients in a single call. The transfer is atomic. If any leg fails (insufficient balance, inactive participant, inactive program), the entire transfer is rolled back and nothing moves. Both the source and every recipient must have ACTIVE status, and the program itself must be ACTIVE. For assets using LOT mode, lots are consumed FIFO from the source and new lots are created for each recipient. The lot vintage resets on transfer, so the recipient’s lot created_at reflects the transfer time, not the original issuance.
For usage patterns and examples, see the Transfers guide.

Authorizations

​
X-API-Key
string
header
required

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

Body

application/json

Transfer details with source and recipients

​
asset_id
string<uuid>
required

Asset being transferred

Example:

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

​
description
string
required

Human-readable explanation of the transfer's purpose

Required string length: 1 - 500
Example:

"Monthly bonus distribution"

​
program_id
string<uuid>
required

Program this transfer belongs to

Example:

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

​
recipients
object[]
required

List of transfer recipients (1 to 100)

Required array length: 1 - 100 elements
​
idempotency_key
string

Unique key to prevent duplicate transfers (optional)

Example:

"txn_abc123"

​
source_external_id
string

Source participant's external ID (mutually exclusive with source_group_id and source_participant_id)

Example:

"user_123"

​
source_group_id
string<uuid>

Source group UUID (mutually exclusive with source_external_id and source_participant_id)

Example:

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

​
source_participant_id
string

Source participant UUID (mutually exclusive with source_external_id and source_group_id)

Response

Transfer completed with journal entry ID

​
asset_id
string<uuid>

Asset that was transferred

Example:

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

​
journal_entry_id
string<uuid>

Journal entry created for this transfer (use for audit trails)

Example:

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

​
recipient_count
integer

Number of recipients in this transfer

Example:

5

​
source_id
string<uuid>

Scrip's UUID for the source participant

Example:

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

​
total_amount
string

Sum of all recipient amounts

Example:

"500.00"