curl --request POST \
--url https://api.citadel.example/api/v1/policy/drafts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"chains": {
"tron": {
"whitelist": [
"TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj",
"TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4"
],
"assets": {
"native": "TRX/6",
"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t": "USDT/6"
},
"wallets": {}
}
},
"ceiling": {
"TRX/6": "100000000",
"USDT/6": "50000000"
},
"references": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
chains: {
tron: {
whitelist: ['TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj', 'TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4'],
assets: {native: 'TRX/6', TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: 'USDT/6'},
wallets: {}
}
},
ceiling: {'TRX/6': '100000000', 'USDT/6': '50000000'},
references: {}
})
};
fetch('https://api.citadel.example/api/v1/policy/drafts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.citadel.example/api/v1/policy/drafts"
payload = {
"chains": { "tron": {
"whitelist": ["TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj", "TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4"],
"assets": {
"native": "TRX/6",
"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t": "USDT/6"
},
"wallets": {}
} },
"ceiling": {
"TRX/6": "100000000",
"USDT/6": "50000000"
},
"references": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.citadel.example/api/v1/policy/drafts"
payload := strings.NewReader("{\n \"chains\": {\n \"tron\": {\n \"whitelist\": [\n \"TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj\",\n \"TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4\"\n ],\n \"assets\": {\n \"native\": \"TRX/6\",\n \"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\": \"USDT/6\"\n },\n \"wallets\": {}\n }\n },\n \"ceiling\": {\n \"TRX/6\": \"100000000\",\n \"USDT/6\": \"50000000\"\n },\n \"references\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}{
"version": 123,
"status": "draft",
"document": "<string>",
"key_id": "<string>",
"signature": "<string>",
"approval": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "pending",
"required": 123,
"approved": 123,
"expires_at": "2023-11-07T05:31:56Z",
"decided_at": "2023-11-07T05:31:56Z"
},
"rejected_reason": "approval_rejected",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}Draft the policy document
Drafts a new version of your policy document from your backend: the whitelist of each chain (your address book), the assets your engine recognises, the ceilings and limits. See Address book for the whole round.
The body is the whole document — what you leave out is not in it. An empty whitelist
lets your engine pay no external address; an asset without a ceiling cannot be sent.
Citadel stamps the next version and each chain’s module version and answers document:
the exact YAML bytes your policy key signs. Before you sign, parse document and check that
it says what you sent. Then sign those bytes, unchanged, with your policy key (key B) and
hand the signature to POST /policy/publish.
There is one draft per organization: a new draft replaces the one waiting to be signed,
whether it was made here or in the console. Rules equal to the change already waiting for
approval answer that change (200, status: pending) and leave the draft as it was. Rules
equal to the version in force are refused with 422 nothing_changed.
A field the document does not have, an address its chain cannot parse, an amount that is
not an integer string, or a window that is not a duration is refused with 422 before the
draft is replaced. One document rules every network and every vault: it takes no
network. Needs the policy.write scope. A key limited to vaults is refused with
403 vault_limited.
curl --request POST \
--url https://api.citadel.example/api/v1/policy/drafts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"chains": {
"tron": {
"whitelist": [
"TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj",
"TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4"
],
"assets": {
"native": "TRX/6",
"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t": "USDT/6"
},
"wallets": {}
}
},
"ceiling": {
"TRX/6": "100000000",
"USDT/6": "50000000"
},
"references": {}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
chains: {
tron: {
whitelist: ['TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj', 'TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4'],
assets: {native: 'TRX/6', TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: 'USDT/6'},
wallets: {}
}
},
ceiling: {'TRX/6': '100000000', 'USDT/6': '50000000'},
references: {}
})
};
fetch('https://api.citadel.example/api/v1/policy/drafts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.citadel.example/api/v1/policy/drafts"
payload = {
"chains": { "tron": {
"whitelist": ["TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj", "TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4"],
"assets": {
"native": "TRX/6",
"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t": "USDT/6"
},
"wallets": {}
} },
"ceiling": {
"TRX/6": "100000000",
"USDT/6": "50000000"
},
"references": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.citadel.example/api/v1/policy/drafts"
payload := strings.NewReader("{\n \"chains\": {\n \"tron\": {\n \"whitelist\": [\n \"TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj\",\n \"TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4\"\n ],\n \"assets\": {\n \"native\": \"TRX/6\",\n \"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\": \"USDT/6\"\n },\n \"wallets\": {}\n }\n },\n \"ceiling\": {\n \"TRX/6\": \"100000000\",\n \"USDT/6\": \"50000000\"\n },\n \"references\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}{
"version": 123,
"status": "draft",
"document": "<string>",
"key_id": "<string>",
"signature": "<string>",
"approval": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "pending",
"required": 123,
"approved": 123,
"expires_at": "2023-11-07T05:31:56Z",
"decided_at": "2023-11-07T05:31:56Z"
},
"rejected_reason": "approval_rejected",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}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.
Body
The whole policy document, less what Citadel stamps (version, each chain's chain_module_version).
The address-bound rules of each chain you use, keyed by chain: tron, evm, solana, ton.
Show child attributes
Show child attributes
The most one transaction may move, per asset key (SYMBOL/decimals), in base units. An asset with no ceiling cannot be sent.
Show child attributes
Show child attributes
Limits per end_user_ref, each one listed by name — never matched by a pattern. {} for none. Payouts to your whitelist go without a request signature, so your engine counts them all under the reserved reference system:whitelisted, not under their end_user_ref: limit them there. With allow_unregistered_reference off, list it, or those payouts are refused.
Show child attributes
Show child attributes
Accept an end_user_ref that references does not list. Leave it off when you set per-reference limits.
Response
These rules already wait for approval — the change that carries them. Nothing to sign.
draft — to sign and publish; pending — signed, waits for approval; published — sent to your engine; rejected — never sent.
draft, pending, published, rejected The YAML document: the exact bytes your policy key signs.
The policy key that signed. null for a draft.
Your policy key's signature over document, in standard base64. null for a draft.
The approval a change published through the API waits for, or waited for. null for a draft, and for a version published in the console.
Show child attributes
Show child attributes
Why a rejected change was never sent: an approver declined it, it was not approved in time, or a newer change replaced it or a newer version came into force first.
approval_rejected, approval_expired, superseded, null