Address book

Your policy engine pays an external address only when the policy document in force lists it in that chain’s whitelist. The document is yours. Your policy key (key B) signs it, and your engine verifies the signature and installs the document. Citadel never signs a policy document. From your backend you keep the whitelist, your address book, in step with your own records. You draft the document, check it, sign it and publish it. People with passkeys approve each change before it reaches your engine.

The round

Draft

POST /policy/drafts with the whole document. The answer carries document: the exact bytes to sign.

Check

Parse document and make sure it says what you sent. Sign only bytes you have read.

Sign

Sign the bytes of document with your policy key (key B), in your engine’s OpenBao.

Publish

POST /policy/publish with version and the signature. The change is pending: it waits for approval.

Approval

People approve it in the console. Citadel then sends it to your engine. GET /policy/drafts/{version} reads published, and GET /policy reads the document in force.

Writing needs a key with the policy.write scope. Reading needs read. A key limited to vaults can do neither: one document rules every vault. No call here takes network: one document rules every network.

Draft the whole document

The body is the whole document: the rules of each chain you use, the ceilings and the per-reference limits. A section you leave out is empty, not kept from the version in force. An empty whitelist lets your engine pay no external address, and an asset without a ceiling cannot be sent. GET /policy returns the document in force, so a change can start from it.

curl -X POST https://api.citadel.example/api/v1/policy/drafts \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chains": {
      "tron": {
        "whitelist": ["TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj", "TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4"],
        "assets": { "native": "TRX/6", "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t": "USDT/6" },
        "wallets": {}
      }
    },
    "ceiling": { "TRX/6": "100000000", "USDT/6": "50000000" },
    "references": {}
  }'

{
  "version": 4,
  "status": "draft",
  "document": "---\nceiling:\n  TRX/6: '100000000'\n  USDT/6: '50000000'\nchains:\n  tron:\n    assets:\n      TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t: USDT/6\n      native: TRX/6\n    chain_module_version: 1\n    wallets: {}\n    whitelist:\n    - TGz2TZmabrZZowj7G8BbyMYg6HacJLuzaj\n    - TVsjquD89kcRu2WTSWsoJhYMNLQbFt8xQ4\nreferences: {}\nversion: 4\n",
  "key_id": null,
  "signature": null,
  "approval": null,
  "rejected_reason": null,
  "created_at": "2026-10-18T09:00:00Z",
  "updated_at": "2026-10-18T09:00:00Z"
}

Citadel adds two things to your rules: the next version, and each chain’s chain_module_version, the address format the chain’s rules are written in. Both are inside the signed bytes. Your engine keeps the highest version it has seen, so an old document can never come back. Citadel refuses the draft with 422 before it replaces anything when it is not a document your engine can read. That covers a field the document does not have, an address its chain cannot parse, an amount that is not an integer string, and a window that is not a duration such as 24h. 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.

Check before you sign

Your engine trusts your policy key’s signature and nothing else. Read the bytes before you sign them. The document is your body plus version and each chain’s chain_module_version. Nothing else is in it:

import yaml

# draft: the answer of POST /policy/drafts; sent: the body you posted
doc = yaml.safe_load(draft["document"])
assert doc.pop("version") == draft["version"]
for rules in doc["chains"].values():
    rules.pop("chain_module_version")
assert doc == sent, "the draft is not what we sent: do not sign it"

Sign with key B

Key B is the policy key in your engine’s OpenBao, and it never leaves it. Sign the bytes of document exactly as answered: UTF-8, the trailing newline included. Write them to a file rather than a shell variable, which drops the trailing newline:

jq -j .document draft.json > policy.yaml   # -j: the string as it is, nothing added or dropped

Through your policy engine’s image. citadel policy-engine sign-policy reads the document on stdin and prints the signature in hex, on the line after signature. Run it inside the engine’s container, which already holds the OpenBao login:

# Helm
kubectl -n citadel-engine exec -i deploy/citadel-engine-engine -- \
  /citadel policy-engine sign-policy --out /dev/null /dev/stdin < policy.yaml
# VM, on an engine host
docker exec -i citadel-engine /citadel policy-engine sign-policy --out /dev/null /dev/stdin < policy.yaml

OpenBao directly. Ed25519 signs the whole message, so digest carries the document’s bytes themselves, hex-encoded, and not a hash of them. The answer’s data.signature is the signature in hex:

curl -X POST "$ENGINE_OPENBAO_ADDR/v1/multichainsign/keys/policy/sign" \
  -H "X-Vault-Token: $POLICY_SIGNING_TOKEN" \
  -d "{\"curve\": \"ed25519\", \"path\": \"m/0'\", \"digest\": \"$(xxd -p policy.yaml | tr -d '\n')\"}"

A backend that can sign with key B can propose any rules. Give it a token that may update multichainsign/keys/policy/sign and nothing else. Keep that token apart from the one that signs payout requests with key A (keys/request/sign). The approval is the people’s check on what it proposes.

Publish and wait for approval

curl -X POST https://api.citadel.example/api/v1/policy/publish \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "version": 4, "signature": "dQhrBoRLDdj261cqTZkE1y3lLxq4fkEp/QrHPyFqMhSgkP4/iVx/xghGu3ExStse1SqOK/JMhlDvitcG0WQhBA==" }'

The signature goes in hex, as sign-policy prints it, or in standard base64. Citadel checks it against the policy key your engine registered when it joined, and answers 202 with status: pending. The change does not reach your engine yet. An approval request opens in the console with the bar of your approval rules in force. It needs as many approvals as their strictest rule asks, from that rule’s group. When no approval rules are in force, or they hold nothing, one member of your organization approves. Every approver confirms with a passkey. Approvers see every whitelist address added and removed, in full, and the other parts of the document the change touches. Follow the change with GET /policy/drafts/{version}:

`status`	What it means	What to do
`draft`	Not signed yet.	Check, sign, publish.
`pending`	Signed; `approval` shows how many approvals it needs, how many it has and until when.	Wait.
`published`	Approved and sent to your engine, which verifies the signature again and installs it.	`GET /policy` reads it in force.
`rejected`	Never sent. `rejected_reason` says why: `approval_rejected` (an approver declined), `approval_expired` (not approved in time), `superseded` (a newer change replaced it, or a newer version came into force first).	Draft again if the change is still wanted.

A rejected version number is never used again. The next draft takes the one after it.

Keep it in step

A backend that syncs its address book on a schedule can run the same round every time:

201: the rules changed. Check, sign, publish.
200 with status: pending: these rules already wait for approval. Nothing to sign; the draft is left as it was.
422 with code: nothing_changed: these are the rules in force. Nothing to do.

A newer change replaces one still waiting, and the approvals it had are lost. A version published in the console in the meantime does the same. Publish again only when your records changed. Sending the same version and signature again answers the change as it stands. A retry after a lost answer is safe.

When it is refused

Status	`code`	Meaning
`404`	—	`POST /policy/publish` names a version with no draft.
`409`	`not_a_draft`	This version is signed already, with another signature. Draft a new version.
`409`	`policy_key_missing`	No policy key is registered for your organization. Your policy engine registers it when it joins.
`422`	`invalid_signature`	Not a 64-byte Ed25519 signature in hex or base64.
`422`	`signature_mismatch`	It does not verify over the draft’s bytes with your policy key. Other bytes were signed (the draft changed, or `document` was altered before signing), or another key signed.
`422`	`nothing_changed`	`POST /policy/drafts` with the rules in force.
`422`	—	Not a document your engine can read: the message names the field.

Nothing changes on a refusal. See Errors for the codes every endpoint shares.

Get started

Merchant stack

Conventions

Notifications

Policy

The round

Draft the whole document

Check before you sign

Sign with key B

Publish and wait for approval

Keep it in step

When it is refused

​The round

​Draft the whole document

​Check before you sign

​Sign with key B

​Publish and wait for approval

​Keep it in step

​When it is refused

The round

Draft the whole document

Check before you sign

Sign with key B

Publish and wait for approval

Keep it in step

When it is refused