Market Data
Get Custody Balance
Read a wallet’s tradable balance, net of its own reservations
GET
/
orderbooks
/
external-securities
/
api
/
custody
/
{custodyContract}
/
balance
/
{userAddress}
/
{tokenAddress}
curl "https://api.trusset.org/orderbooks/external-securities/api/custody/0x489aee4ae9546081d55848f157e03192e826988c/balance/0xabc7f1093d5e26b804a1c3f78de025916b47c0d3/0x98ad0ca091552e23c564b41c74282e5343d03e8a" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/orderbooks/external-securities/api/custody/${custody}/balance/${user}/${token}`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
console.log('tradable', data.available, 'reserved', data.reserved);
{
"success": true,
"data": {
"total": "100000000000",
"locked": "50000000000",
"onChainAvailable": "50000000000",
"reserved": "1042000000",
"available": "48958000000"
}
}
Returns what one wallet can actually trade of one token, in that token’s base units.
Nothing is escrowed on this venue, so these are not custody holdings. For the security they describe the holder’s own unfrozen balance; for the settlement asset they describe the lesser of balance and the allowance granted to the custody contract. Both are then reduced by everything this venue has reserved against the wallet’s own resting orders.
That last subtraction is the point. The chain cannot see an off-chain reservation, so publishing the raw number would overstate inventory by exactly the trader’s own quotes and then refuse their next order. This endpoint answers with the same figure the order gate uses.
Path Parameters
string
required
Custody contract address. Use the address from Get Custody Contract.
string
required
Wallet to read.
string
required
Token to read. Either side of a pair.
Response Fields
object
Show child attributes
Show child attributes
string
The wallet’s balance as the contract reports it.
string
The portion the contract reports as unavailable, such as frozen tokens.
string
What the contract reports as available, before this venue’s reservations.
string
Committed to this wallet’s resting orders on this venue.
string
onChainAvailable minus reserved. What a new order can draw on.A read that fails answers with zeros rather than an error. Treat an unexpected zero as suspect if the wallet is known to be funded, and use Get Trade Readiness, which surfaces a chain failure explicitly.
curl "https://api.trusset.org/orderbooks/external-securities/api/custody/0x489aee4ae9546081d55848f157e03192e826988c/balance/0xabc7f1093d5e26b804a1c3f78de025916b47c0d3/0x98ad0ca091552e23c564b41c74282e5343d03e8a" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/orderbooks/external-securities/api/custody/${custody}/balance/${user}/${token}`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
console.log('tradable', data.available, 'reserved', data.reserved);
{
"success": true,
"data": {
"total": "100000000000",
"locked": "50000000000",
"onChainAvailable": "50000000000",
"reserved": "1042000000",
"available": "48958000000"
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
VALIDATION_ERROR | 400 | One of the three path addresses is malformed |
SERVICE_NOT_ENABLED | 403 | The Trading service is not enabled on this instance |
⌘I
curl "https://api.trusset.org/orderbooks/external-securities/api/custody/0x489aee4ae9546081d55848f157e03192e826988c/balance/0xabc7f1093d5e26b804a1c3f78de025916b47c0d3/0x98ad0ca091552e23c564b41c74282e5343d03e8a" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/orderbooks/external-securities/api/custody/${custody}/balance/${user}/${token}`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
console.log('tradable', data.available, 'reserved', data.reserved);
{
"success": true,
"data": {
"total": "100000000000",
"locked": "50000000000",
"onChainAvailable": "50000000000",
"reserved": "1042000000",
"available": "48958000000"
}
}