curl --request POST \
--url https://api.citadel.example/api/v1/wallets/{reference}/retire \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.citadel.example/api/v1/wallets/{reference}/retire', 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}/retire"
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/wallets/{reference}/retire"
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))
}{
"id": "0199a3c4-7f1e-7b11-9c2e-3f4a5b6c7d8e",
"reference": "user-4211",
"chain": "tron",
"network": "mainnet",
"address": "TC6A9sQD2tCSaR1wcBXZtrvGkFyoLgRHHF",
"status": "retired",
"label": "deposit",
"tags": [
"vip"
],
"end_user_ref": "user-4211",
"vault": "0199a3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"created_at": "2026-10-07T12:00:00Z"
}Retire a wallet
Takes an active wallet out of circulation — a user who left, an address you no longer show.
It ends retired for good: a retired wallet does not come back, and a new address for the
user is a new wallet, under a new reference. The wallet.retired webhook follows.
A retired wallet is out of circulation, not out of sight:
- its address is still watched: a deposit that still arrives on it is credited to it, and
reported as any deposit is (
blockchain_event.confirmed,GET /transfers); - it still sends with
POST /transactions, so you can move out what arrives; - workflows no longer pick it, and a workflow step does not send from it;
GET /walletslists it withstatus: retired, andGET /wallets/{reference}reads it.
Retiring it again answers the same 200, without a second webhook. A wallet with no address
does not retire: 409 not_retirable while it is creating, and for a failed one. A token
sub-account Citadel keeps under a wallet follows that wallet: it is retired with it, also
one Citadel opens later, so no workflow reaches the wallet through its address. Retiring one
on its own is refused with 422.
network is required: a reference names a wallet within it. Needs the wallets.write
scope. A wallet outside the key’s vaults answers 404.
curl --request POST \
--url https://api.citadel.example/api/v1/wallets/{reference}/retire \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.citadel.example/api/v1/wallets/{reference}/retire', 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}/retire"
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/wallets/{reference}/retire"
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))
}{
"id": "0199a3c4-7f1e-7b11-9c2e-3f4a5b6c7d8e",
"reference": "user-4211",
"chain": "tron",
"network": "mainnet",
"address": "TC6A9sQD2tCSaR1wcBXZtrvGkFyoLgRHHF",
"status": "retired",
"label": "deposit",
"tags": [
"vip"
],
"end_user_ref": "user-4211",
"vault": "0199a3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"created_at": "2026-10-07T12: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
Retired — now, or by an earlier call. The wallet as it now reads.
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 creating — issued, your signer has not derived it yet; active — in circulation;
retired — out of circulation (POST /wallets/{reference}/retire): still watched,
credited, and able to send; failed — your signer could not derive it, it has no address.
creating, active, retired, failed Absent while creating, and on a failed wallet.
The vault the wallet is in.