Transaction requests
How a Treasury transaction moves from request to on-chain finality, and what each status means
Every transfer from a Treasury vault is a transaction request. Treasury records the request, your signers approve it in io.sign, and Treasury broadcasts the signed transaction and tracks it on chain. The request's status tells you where it is in that workflow.
Workflow
- Build. Call a build endpoint for the chain, such as
build-native-transactionorbuild-token-transaction. Treasury returns the unsigned transaction and a readable summary. Building creates nothing and needs no approval. - Submit. Submit the built transaction to create the request. Send an
idempotency-keyheader so a retried call can't create a second request. - Approve. Treasury opens an io.sign signature request for the vault. Your signers review and approve it until their combined weight meets the vault's threshold.
- Sign. The approving signers produce the signature with io.sign Multi-Party Computation (MPC).
- Broadcast. Treasury attaches the signature and broadcasts the transaction, unless you created the request with
broadcastset tofalse. - Confirm. Treasury tracks the transaction on chain until it is final.
Status lifecycle
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#E8EEFB", "primaryTextColor": "#07112B", "primaryBorderColor": "#003EB7", "lineColor": "#8A96B4", "edgeLabelBackground": "#F4F6FA", "fontSize": "14px"}, "flowchart": {"curve": "basis", "nodeSpacing": 30, "rankSpacing": 45}}}%%
flowchart TD
submit(["Submit"]) --> pending["pending"]
pending -->|"io.sign request opened"| sfs["submitted_for_signature"]
sfs -->|"Approved and signed"| broadcast["broadcast"]
sfs -->|"EVM, XRP, or Liquid"| signed["signed"]
sfs -->|"broadcast set to false"| wtb["waiting_to_broadcast"]
sfs -->|"Signature-only request"| fulfilled["fulfilled"]
signed -->|"Its turn comes"| broadcast
wtb -->|"You call broadcast"| broadcast
sfs -->|"Declined, deadline passed, or cancelled"| stopped["rejected / expired / cancelled"]
pending -. "Error" .-> failed["failed"]
sfs -. "Signing error" .-> failed
signed -. "Broadcast refused" .-> failed
wtb -. "Broadcast refused" .-> failed
broadcast -. "Reverted on chain" .-> failed
classDef active fill:#E8EEFB,stroke:#003EB7,color:#07112B
classDef success fill:#E3F4EF,stroke:#0E7C66,color:#07112B,font-weight:bold
classDef stopped fill:#FDECEC,stroke:#E03737,color:#07112B
classDef start fill:#07112B,stroke:#07112B,color:#FFFFFF
class pending,sfs,signed,wtb active
class broadcast,fulfilled success
class stopped,failed stopped
class submit start
Blue statuses are in progress, green statuses are successful, and red statuses are final without a successful transaction. Dotted lines lead to failed.
Statuses
| Status | Meaning | Final? |
|---|---|---|
pending | Treasury has recorded the request and is opening the io.sign request. | No |
submitted_for_signature | Waiting for your signers to approve and sign in io.sign. | No |
signed | Signed, and waiting for its turn to broadcast. Used on EVM and XRP, where transactions from one address must go out in nonce or sequence order, and on Liquid while AMP2 co-signs. | No |
waiting_to_broadcast | Signed and held because you set broadcast to false. Call the broadcast endpoint to send it. | No |
broadcast | Sent to the network. Follow its on-chain status for confirmation. | Yes |
fulfilled | A signature-only request has its signature. Nothing is broadcast. | Yes |
rejected | A signer declined the request in io.sign. | Yes |
expired | The approval deadline passed before the threshold was met. | Yes |
cancelled | The request was cancelled in io.sign. | Yes |
failed | The request couldn't complete. failureReason says why. | Yes |
broadcast and fulfilled are the successful outcomes. A broadcast request can still become failed if the transaction reverts on chain. Rarely, a request marked failed after a node refused the broadcast moves to broadcast, because a duplicate broadcast reached the network first. Reconcile against the on-chain status rather than treating failed as final for accounting.
The completed status is retired. Filtering by completed still works and returns requests that are broadcast and confirmed or finalised, but no request has that status.
On-chain status
After a request reaches broadcast, its onChainTransaction.status tracks the transaction on the network:
| On-chain status | Meaning |
|---|---|
pending | In the network's mempool, not yet in a block. |
confirmed | Included in a block. |
finalized | Final under the network's rules. The request is settled. |
failed | Included in a block but reverted. The request becomes failed. |
orphaned | Its block was dropped in a reorganisation. Watch for it to be included again. |
XRP and io.network transactions go straight from pending to finalized.
Approval deadline
Set expiryTimestamp when you submit to give signers a deadline. If you leave it out, io.sign's default deadline applies. Treasury never expires a request itself: it becomes expired only when io.sign reports that the deadline has passed.
Ordered broadcasts on EVM and XRP
On EVM networks and XRP, Treasury assigns each request its nonce or sequence number just before signing, and broadcasts each address's transactions in order. If a request fails, the requests queued behind it from the same address fail too, so a gap in the sequence can't block the address. Submit them again once you have fixed the cause.
Blockaid screening
Treasury scans each request on public EVM networks and Solana when you submit it, and you can scan a built transaction before submitting it. The verdict is benign, suspicious, malicious, or unavailable.
Screening is advisory: a verdict doesn't change the request's status or stop it. Check the verdict before your signers approve, and have them reject a request you don't trust. See Blockaid screening for rescans and scan history.
Track a request
Poll the request by its ID, or list requests filtered by status or on-chain status. You can also look a request up by its transaction hash. A request's status never moves backwards, except in the cases described above.
Updated 17 days ago