curl --request GET \
--url https://api.citadel.example/api/v1/wallets/{reference}/limits \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.citadel.example/api/v1/wallets/{reference}/limits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.citadel.example/api/v1/wallets/{reference}/limits"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.citadel.example/api/v1/wallets/{reference}/limits"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"reference": "user-4211",
"chain": "tron",
"network": "mainnet",
"end_user_ref": "user-4211",
"limits": [
{
"scope": "wallet",
"asset": "USDT/6",
"window": "24h0m0s",
"limit": "10000000000",
"used": "2500000000",
"remaining": "7500000000",
"window_start": "2026-10-07T12:00:00Z",
"window_end": "2026-10-09T12:00:00Z",
"as_of": "2026-10-08T12:00:00Z"
},
{
"scope": "end_user_ref",
"asset": "USDT/6",
"window": "24h0m0s",
"limit": "1000000000",
"used": "900000000",
"remaining": "100000000",
"window_start": "2026-10-07T12:00:00Z",
"window_end": "2026-10-09T12:00:00Z",
"as_of": "2026-10-08T12:00:00Z"
}
]
}Get a wallet's limits
What your policy engine last said about the limits a payout from this wallet runs into:
the wallet’s own ceiling (scope: wallet) and, when the wallet has an end_user_ref, that
end user’s (scope: end_user_ref). For reference only, before a payout: your policy engine
decides every payout on its own count, so a payout that fits here can still fail
policy_refused.
The wallet’s figure counts every payout from it. The end user’s counts the payouts that
name them as end_user_ref, from any wallet, to addresses outside your whitelist. A
payout to a whitelisted address goes without a request signature, so your engine does
not take its end_user_ref on trust: it counts it under the reserved reference
system:whitelisted, shared by every payout to your whitelist, and it is not in the end
user’s figure. Moves between your own wallets count against no limit.
Citadel computes no limit. Your engine signs its counters with every payout it approves,
and this is the last one it signed for the wallet and for its end user. Each counter is as
of its as_of: since then, spends older than the window have rolled off, and payouts your
engine signed later are not in it until their decision arrives. By window_end, everything
counted in it has rolled off. Until your engine approves a payout from the wallet or for
its end user, there are no counters: limits is empty — an unknown ceiling, not a zero.
network is required. Needs the read scope. A wallet outside the key’s vaults answers
404.
curl --request GET \
--url https://api.citadel.example/api/v1/wallets/{reference}/limits \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.citadel.example/api/v1/wallets/{reference}/limits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.citadel.example/api/v1/wallets/{reference}/limits"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.citadel.example/api/v1/wallets/{reference}/limits"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"reference": "user-4211",
"chain": "tron",
"network": "mainnet",
"end_user_ref": "user-4211",
"limits": [
{
"scope": "wallet",
"asset": "USDT/6",
"window": "24h0m0s",
"limit": "10000000000",
"used": "2500000000",
"remaining": "7500000000",
"window_start": "2026-10-07T12:00:00Z",
"window_end": "2026-10-09T12:00:00Z",
"as_of": "2026-10-08T12:00:00Z"
},
{
"scope": "end_user_ref",
"asset": "USDT/6",
"window": "24h0m0s",
"limit": "1000000000",
"used": "900000000",
"remaining": "100000000",
"window_start": "2026-10-07T12:00:00Z",
"window_end": "2026-10-09T12:00:00Z",
"as_of": "2026-10-08T12:00:00Z"
}
]
}Authorizations
An API key minted in the console (ctd_…). Authenticates; never authorizes funds. A key
carries scopes (read, wallets.write, transactions.write, events.write,
webhooks.write, policy.write) and may be limited to vaults, to IP addresses, and in
lifetime — see Authentication.
Path Parameters
Your reference for the wallet, or its id.
Query Parameters
The network the data lives on. Required — there is no default network: without it,
422 network_required. A wallet named by its id on another network: 422 network_mismatch.
The network the data lives on. Required wherever it appears in a request — there is no
default network. One your installation does not serve: 422 network_not_served.
mainnet, testnet Response
The wallet's limits, as your policy engine last signed them.
tron, evm, solana, ton The network the data lives on. Required wherever it appears in a request — there is no
default network. One your installation does not serve: 422 network_not_served.
mainnet, testnet The wallet's end user, whose limits scope: end_user_ref rows are.
Empty until your policy engine approves a payout from the wallet or for its end user.
Show child attributes
Show child attributes