curl --request POST \
--url https://api.citadel.example/api/v1/transactions/{id}/cancel \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.citadel.example/api/v1/transactions/{id}/cancel', 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/{id}/cancel"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.citadel.example/api/v1/transactions/{id}/cancel"
req, _ := http.NewRequest("POST", 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))
}{
"operation_id": "0199a3c4-8a00-7c22-8d3e-4f5a6b7c8d9e",
"status": "failed",
"network": "mainnet",
"chain": "tron",
"wallet": {
"id": "0199a3b1-5e20-7d41-9c3a-2b4c6d8e0f12",
"reference": "hot-1",
"address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
},
"actions": [
{
"type": "transfer",
"to": "TC6A9sQD2tCSaR1wcBXZtrvGkFyoLgRHHF",
"amount": "50000000000",
"asset": "USDT",
"contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"decimals": 6
}
],
"end_user_ref": "user-4211",
"tags": [],
"idempotency_key": "payout-981",
"failure": {
"stage": "approval",
"reason": "cancelled",
"retryable": false,
"message": "The payout was cancelled before it was signed. Nothing was signed or moved."
},
"approval": {
"id": "0199a3c4-9b10-7d33-9e4f-5a6b7c8d9e0f",
"status": "cancelled",
"required": 2,
"reasons": [
"Amount step $10000 and above"
],
"group": "Treasury",
"rule_version": 3,
"requested_at": "2026-10-08T12:00:00Z",
"expires_at": "2026-10-08T16:00:00Z",
"decided_at": "2026-10-08T12:03:00Z",
"decisions": []
},
"created_at": "2026-10-08T12:00:00Z",
"updated_at": "2026-10-08T12:03:00Z"
}Cancel a transaction
Withdraws a transaction while nothing of it is signed yet:
- held by your approval rules (
status: awaiting_approval): its quorum request closes (approval.status: cancelled), so nobody can approve it any more, and the amounts and the network fee held for it are spendable again; - queued (
queue: true) and not yet picked up by a workflow’s batch: it held nothing.
The transaction ends failed with failure.reason: cancelled, and the operation.failed
webhook follows. The answer is the transaction, the body GET /transactions/{id} reads.
Cancelling it again answers the same 200.
Otherwise it is 409 not_cancellable, and nothing changes. From authorized on, the
transaction is on its way to your signer, signed, on chain or ended, and the error says
which. A quorum that has already decided stands: approved, it is being sent; rejected or
expired, it fails on its own. A queued payout a batch already carries goes with the batch.
Only what your API keys sent can be cancelled: a transaction a workflow sent stops with
its run (POST /runs/{id}/cancel), and the ones Citadel makes for itself cannot be.
Takes the operation_id or the idempotency key, like GET /transactions/{id}, and no
network. Needs the transactions.write scope. A transaction from a wallet outside the
key’s vaults answers 404.
curl --request POST \
--url https://api.citadel.example/api/v1/transactions/{id}/cancel \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.citadel.example/api/v1/transactions/{id}/cancel', 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/{id}/cancel"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.citadel.example/api/v1/transactions/{id}/cancel"
req, _ := http.NewRequest("POST", 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))
}{
"operation_id": "0199a3c4-8a00-7c22-8d3e-4f5a6b7c8d9e",
"status": "failed",
"network": "mainnet",
"chain": "tron",
"wallet": {
"id": "0199a3b1-5e20-7d41-9c3a-2b4c6d8e0f12",
"reference": "hot-1",
"address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
},
"actions": [
{
"type": "transfer",
"to": "TC6A9sQD2tCSaR1wcBXZtrvGkFyoLgRHHF",
"amount": "50000000000",
"asset": "USDT",
"contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"decimals": 6
}
],
"end_user_ref": "user-4211",
"tags": [],
"idempotency_key": "payout-981",
"failure": {
"stage": "approval",
"reason": "cancelled",
"retryable": false,
"message": "The payout was cancelled before it was signed. Nothing was signed or moved."
},
"approval": {
"id": "0199a3c4-9b10-7d33-9e4f-5a6b7c8d9e0f",
"status": "cancelled",
"required": 2,
"reasons": [
"Amount step $10000 and above"
],
"group": "Treasury",
"rule_version": 3,
"requested_at": "2026-10-08T12:00:00Z",
"expires_at": "2026-10-08T16:00:00Z",
"decided_at": "2026-10-08T12:03:00Z",
"decisions": []
},
"created_at": "2026-10-08T12:00:00Z",
"updated_at": "2026-10-08T12:03: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
The operation_id, or the idempotency key — yours, or the intent:<uuid> Citadel returned for a request sent without one.
Response
Cancelled — now, or by an earlier call.
A transaction. A field with nothing to say is absent, except actions and tags.
created, aml_pending, awaiting_approval, authorized, signing, signed, broadcasting, broadcast, confirmed, final, failed, rejected, expired What it does, in order — the actions you sent, each asset named as balances name it.
Show child attributes
Show child attributes
When Citadel accepted it.
Its last change of state.
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 leaves from.
Show child attributes
Show child attributes
Known from broadcasting on.
The network fee the landed transaction cost, in the native coin of the chain it landed on. Absent until it lands.
Show child attributes
Show child attributes
The key the request was sent with. A request sent without one gets
intent:<uuid>, unique to this transaction; GET /transactions/{id} takes it too.
true while a queued payout (queue: true) waits for its workflow; absent otherwise.
Show child attributes
Show child attributes
The transaction was declared expired, then landed after all (the chain index served it
late). The earlier verdict is withdrawn — if you resubmitted on it, that payout is a
second one.
Show child attributes
Show child attributes
An EVM transaction waits behind its nonce: no node has taken its signed bytes for 5
minutes (the operation.stuck webhook). It keeps its holds and is sent again and again,
and new transactions from the wallet are refused until it moves. Absent once a node takes
it. POST /transactions/{id}/speedup signs it again at a higher fee.
Show child attributes
Show child attributes
The latest POST /transactions/{id}/speedup of this transaction, and what came of it.
Show child attributes
Show child attributes
Present when your approval rules held the transaction for a passkey quorum — on the
202 and on every read after it. Absent when it went out without waiting for people.
Show child attributes
Show child attributes