curl --request POST \
--url https://api.citadel.example/api/v1/transactions/estimate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"wallet": "hot-1",
"network": "mainnet",
"end_user_ref": "user-4211",
"actions": [
{
"type": "transfer",
"asset": "USDC",
"to": "0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f",
"amount": "25000000000"
}
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
wallet: 'hot-1',
network: 'mainnet',
end_user_ref: 'user-4211',
actions: [
{
type: 'transfer',
asset: 'USDC',
to: '0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f',
amount: '25000000000'
}
]
})
};
fetch('https://api.citadel.example/api/v1/transactions/estimate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.citadel.example/api/v1/transactions/estimate"
payload = {
"wallet": "hot-1",
"network": "mainnet",
"end_user_ref": "user-4211",
"actions": [
{
"type": "transfer",
"asset": "USDC",
"to": "0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f",
"amount": "25000000000"
}
]
}
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/transactions/estimate"
payload := strings.NewReader("{\n \"wallet\": \"hot-1\",\n \"network\": \"mainnet\",\n \"end_user_ref\": \"user-4211\",\n \"actions\": [\n {\n \"type\": \"transfer\",\n \"asset\": \"USDC\",\n \"to\": \"0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f\",\n \"amount\": \"25000000000\"\n }\n ]\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))
}{
"network": "mainnet",
"chain": "evm",
"wallet": {
"id": "0199a3b1-7a42-7f63-9e5c-4d6e8f0a2b34",
"reference": "hot-1",
"address": "0x5f2d8e1a3c4b6d7e9f0a1b2c3d4e5f6a7b8c9d0e"
},
"network_fee": {
"amount": "1260000000000000",
"asset": "ETH",
"decimals": 18
},
"approval": {
"required": 2,
"group": "Treasury",
"reasons": [
"Amount step $10000 and above"
],
"expires_in": 14400,
"rule_version": 3
}
}Estimate a transaction
Takes the body of POST /transactions and answers what sending it now would do, without
sending anything: the network fee Citadel would hold next to the amounts, and whether your
approval rules would hold it for a passkey quorum — how many approvals, from which group,
why, and for how long. Nothing is created, reserved or signed, and no webhook follows.
It refuses what a send refuses, with the same status and code: an unknown wallet, a bad
amount or address, a wallet outside the key’s vaults (403 vault_limited), a wallet id
from another network (422 network_mismatch). network is required. queue, tags and
the idempotency key are not read: an estimate is for sending now.
network_fee is the most the network may charge the sending wallet, in its native coin —
what a send holds for it. Citadel prices it for EVM wallets that pay their own gas. For
every other wallet (TRON, TON, Solana, EVM smart accounts) it is null: a send holds
nothing for the fee, and Citadel does not price it.
What it does not promise. Your policy engine decides only when the transaction is signed, so an estimate never asks it. It does not check the balance: the send may still be refused for insufficient funds. And by the time you send, the balance, the fee and the windows of your velocity rules may have moved — the send is judged afresh.
Needs the transactions.write scope. Your approval rules judge the calling key (its age,
what it sent recently), so estimate with the key that will send.
curl --request POST \
--url https://api.citadel.example/api/v1/transactions/estimate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"wallet": "hot-1",
"network": "mainnet",
"end_user_ref": "user-4211",
"actions": [
{
"type": "transfer",
"asset": "USDC",
"to": "0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f",
"amount": "25000000000"
}
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
wallet: 'hot-1',
network: 'mainnet',
end_user_ref: 'user-4211',
actions: [
{
type: 'transfer',
asset: 'USDC',
to: '0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f',
amount: '25000000000'
}
]
})
};
fetch('https://api.citadel.example/api/v1/transactions/estimate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.citadel.example/api/v1/transactions/estimate"
payload = {
"wallet": "hot-1",
"network": "mainnet",
"end_user_ref": "user-4211",
"actions": [
{
"type": "transfer",
"asset": "USDC",
"to": "0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f",
"amount": "25000000000"
}
]
}
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/transactions/estimate"
payload := strings.NewReader("{\n \"wallet\": \"hot-1\",\n \"network\": \"mainnet\",\n \"end_user_ref\": \"user-4211\",\n \"actions\": [\n {\n \"type\": \"transfer\",\n \"asset\": \"USDC\",\n \"to\": \"0x9a41c7e2b8d05f3a6e1c4b7d2f8a0e3c5b6d7e8f\",\n \"amount\": \"25000000000\"\n }\n ]\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))
}{
"network": "mainnet",
"chain": "evm",
"wallet": {
"id": "0199a3b1-7a42-7f63-9e5c-4d6e8f0a2b34",
"reference": "hot-1",
"address": "0x5f2d8e1a3c4b6d7e9f0a1b2c3d4e5f6a7b8c9d0e"
},
"network_fee": {
"amount": "1260000000000000",
"asset": "ETH",
"decimals": 18
},
"approval": {
"required": 2,
"group": "Treasury",
"reasons": [
"Amount step $10000 and above"
],
"expires_in": 14400,
"rule_version": 3
}
}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
Wallet id, reference, or address on network; a wallet id must live on network. A signed request (X-Citadel-Request-Signature) names it by id or address only.
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 1- transfer
- approve
- swap
- call
Show child attributes
Show child attributes
The user the payout is for; policy limits count per user.
Same as the Idempotency-Key header.
true records the payout for a workflow to send later in a batch, instead of
sending it now. Exactly one transfer action.
At the door nothing is reserved, no network fee is estimated, and your approval
rules are not asked. The funds stay spendable until a workflow's batch payout picks
the payout up by its tags and reserves them for the batch. The answer is 202 with
status: created and queued: true.
Once a batch carries it, the transaction reads final when the batch landed and
failed when it did not. It has no tx_hash of its own, and these changes come
without operation.* webhooks: read them with GET /transactions/{id}. Until a batch
carries it, POST /transactions/{id}/cancel withdraws it, with operation.failed.
Selects a queued payout in a workflow.
Response
What a send would hold and whether it would wait for people.
What sending the request now would do. network_fee and approval are always present; null is an answer.
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 tron, evm, solana, ton The wallet it would leave from.
Show child attributes
Show child attributes
The most the network may charge the sending wallet, in the chain's native coin — what a
send holds next to the amounts. null: Citadel prices no fee for this wallet and a send
holds none (every wallet but an EVM one paying its own gas).
Show child attributes
Show child attributes
The quorum your approval rules would hold the send for — the strictest rule that
matches, every match listed in reasons. null: it would go out without waiting for
people.
Show child attributes
Show child attributes