Adjust group balance
curl --request POST \
--url https://api.scrip.dev/v1/groups/{id}/balances/adjust \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Team bonus allocation",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": false,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-group-123",
"matures_at": "7d"
}
'import requests
url = "https://api.scrip.dev/v1/groups/{id}/balances/adjust"
payload = {
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Team bonus allocation",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": False,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-group-123",
"matures_at": "7d"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '100.00',
asset_id: '550e8400-e29b-41d4-a716-446655440001',
description: 'Team bonus allocation',
program_id: '550e8400-e29b-41d4-a716-446655440000',
type: 'CREDIT',
allow_negative: false,
bucket: 'AVAILABLE',
expires_at: '90d',
idempotency_key: 'adjust-group-123',
matures_at: '7d'
})
};
fetch('https://api.scrip.dev/v1/groups/{id}/balances/adjust', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.scrip.dev/v1/groups/{id}/balances/adjust",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '100.00',
'asset_id' => '550e8400-e29b-41d4-a716-446655440001',
'description' => 'Team bonus allocation',
'program_id' => '550e8400-e29b-41d4-a716-446655440000',
'type' => 'CREDIT',
'allow_negative' => false,
'bucket' => 'AVAILABLE',
'expires_at' => '90d',
'idempotency_key' => 'adjust-group-123',
'matures_at' => '7d'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.scrip.dev/v1/groups/{id}/balances/adjust"
payload := strings.NewReader("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Team bonus allocation\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-group-123\",\n \"matures_at\": \"7d\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.scrip.dev/v1/groups/{id}/balances/adjust")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Team bonus allocation\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-group-123\",\n \"matures_at\": \"7d\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/groups/{id}/balances/adjust")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Team bonus allocation\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-group-123\",\n \"matures_at\": \"7d\"\n}"
response = http.request(request)
puts response.read_body{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"bucket": "AVAILABLE",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Group balance adjusted successfully",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT"
}{
"code": "bad_request",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Invalid request parameters"
}{
"code": "unauthorized",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Missing or invalid credentials"
}{
"code": "forbidden",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Insufficient permissions for this action"
}{
"code": "not_found",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource not found"
}{
"code": "conflict",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource already exists or state conflict"
}{
"code": "unsupported_media_type",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Content-Type must be application/json"
}{
"code": "unprocessable",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Business rule violation"
}{
"code": "internal_error",
"message": "An internal error occurred"
}Balances
Adjust group balance
Manually credit or debit a group’s balance.
POST
/
v1
/
groups
/
{id}
/
balances
/
adjust
Adjust group balance
curl --request POST \
--url https://api.scrip.dev/v1/groups/{id}/balances/adjust \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Team bonus allocation",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": false,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-group-123",
"matures_at": "7d"
}
'import requests
url = "https://api.scrip.dev/v1/groups/{id}/balances/adjust"
payload = {
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"description": "Team bonus allocation",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT",
"allow_negative": False,
"bucket": "AVAILABLE",
"expires_at": "90d",
"idempotency_key": "adjust-group-123",
"matures_at": "7d"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '100.00',
asset_id: '550e8400-e29b-41d4-a716-446655440001',
description: 'Team bonus allocation',
program_id: '550e8400-e29b-41d4-a716-446655440000',
type: 'CREDIT',
allow_negative: false,
bucket: 'AVAILABLE',
expires_at: '90d',
idempotency_key: 'adjust-group-123',
matures_at: '7d'
})
};
fetch('https://api.scrip.dev/v1/groups/{id}/balances/adjust', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.scrip.dev/v1/groups/{id}/balances/adjust",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '100.00',
'asset_id' => '550e8400-e29b-41d4-a716-446655440001',
'description' => 'Team bonus allocation',
'program_id' => '550e8400-e29b-41d4-a716-446655440000',
'type' => 'CREDIT',
'allow_negative' => false,
'bucket' => 'AVAILABLE',
'expires_at' => '90d',
'idempotency_key' => 'adjust-group-123',
'matures_at' => '7d'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.scrip.dev/v1/groups/{id}/balances/adjust"
payload := strings.NewReader("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Team bonus allocation\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-group-123\",\n \"matures_at\": \"7d\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.scrip.dev/v1/groups/{id}/balances/adjust")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Team bonus allocation\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-group-123\",\n \"matures_at\": \"7d\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scrip.dev/v1/groups/{id}/balances/adjust")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"100.00\",\n \"asset_id\": \"550e8400-e29b-41d4-a716-446655440001\",\n \"description\": \"Team bonus allocation\",\n \"program_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"type\": \"CREDIT\",\n \"allow_negative\": false,\n \"bucket\": \"AVAILABLE\",\n \"expires_at\": \"90d\",\n \"idempotency_key\": \"adjust-group-123\",\n \"matures_at\": \"7d\"\n}"
response = http.request(request)
puts response.read_body{
"amount": "100.00",
"asset_id": "550e8400-e29b-41d4-a716-446655440001",
"bucket": "AVAILABLE",
"journal_entry_id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Group balance adjusted successfully",
"program_id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CREDIT"
}{
"code": "bad_request",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Invalid request parameters"
}{
"code": "unauthorized",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Missing or invalid credentials"
}{
"code": "forbidden",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Insufficient permissions for this action"
}{
"code": "not_found",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource not found"
}{
"code": "conflict",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Resource already exists or state conflict"
}{
"code": "unsupported_media_type",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Content-Type must be application/json"
}{
"code": "unprocessable",
"details": {
"expected": "<string>",
"field": "<string>",
"fields": [
{
"expected": "<unknown>",
"field": "<string>",
"message": "This field is required",
"reason": "required",
"received": "<string>"
}
],
"reason": "invalid",
"received": "<string>"
},
"message": "Business rule violation"
}{
"code": "internal_error",
"message": "An internal error occurred"
}Credits or debits a group’s balance for a specific asset within a program. Set
type to CREDIT or DEBIT and provide a positive amount. A DEBIT fails if the group does not have sufficient balance in the target bucket, unless allow_negative is true (used for clawbacks). The optional bucket field selects AVAILABLE or HELD and defaults to AVAILABLE.
You must specify program_id and asset_id to identify which balance to adjust; groups are organization-level entities, but each group maintains separate balances per program-asset pair. The adjustment creates one journal entry whose action_type is CREDIT or DEBIT, matching type, with event_id and rule_id both null. There is no separate adjustment action type. This endpoint mirrors adjust participant balance.
For usage patterns and examples, see the Balance Operations guide, including expiration and maturity on credits.
Authorizations
ApiKeyAuthBearerAuth
API key passed in the X-API-Key header.
Headers
Idempotency key (1-255 printable ASCII chars). Equivalent to the idempotency_key body field; if both are provided they must match. Replays with the same key and identical parameters return the original journal_entry_id; the same key with different parameters returns 409 idempotency_conflict.
Maximum string length:
255Path Parameters
Group ID
Body
application/json
Adjustment details
Adjustment amount (must be positive, decimal string)
Minimum string length:
1Example:
"100.00"
The asset to adjust
Example:
"550e8400-e29b-41d4-a716-446655440001"
Reason for this adjustment (1-500 chars)
Required string length:
1 - 500Example:
"Team bonus allocation"
The program this adjustment belongs to
Example:
"550e8400-e29b-41d4-a716-446655440000"
Whether to CREDIT or DEBIT the balance
Available options:
CREDIT, DEBIT Example:
"CREDIT"
DEBIT only. When true, allows this adjustment to overdraw and set a negative balance.
Example:
false
Balance bucket to adjust: AVAILABLE or HELD (defaults to AVAILABLE)
Available options:
AVAILABLE, HELD Example:
"AVAILABLE"
CREDIT + LOT only. RFC3339 timestamp or positive duration from request processing time. Not supported with bucket HELD.
Required string length:
1 - 255Example:
"90d"
Client-provided key to dedupe retries. May also be supplied via the Idempotency-Key HTTP header; when both are present they must match. Identical adjusts with the same key return the original journal_entry_id; a reused key with different payload returns 409 idempotency_conflict.
Required string length:
1 - 255Example:
"adjust-group-123"
CREDIT + LOT only. RFC3339 timestamp or positive duration from request processing time. Future values route the credit to DEFERRED. Not supported with bucket HELD.
Required string length:
1 - 255Example:
"7d"
Response
Adjustment applied
Amount adjusted
Example:
"100.00"
Asset that was adjusted
Example:
"550e8400-e29b-41d4-a716-446655440001"
Balance bucket that was adjusted
Example:
"AVAILABLE"
Ledger journal entry created by this adjustment
Example:
"550e8400-e29b-41d4-a716-446655440000"
Confirmation message
Example:
"Group balance adjusted successfully"
Program the balance belongs to
Example:
"550e8400-e29b-41d4-a716-446655440000"
Whether the adjustment was a credit or debit
Example:
"CREDIT"