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

  1. Build. Call a build endpoint for the chain, such as build-native-transaction or build-token-transaction. Treasury returns the unsigned transaction and a readable summary. Building creates nothing and needs no approval.
  2. Submit. Submit the built transaction to create the request. Send an idempotency-key header so a retried call can't create a second request.
  3. 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.
  4. Sign. The approving signers produce the signature with io.sign Multi-Party Computation (MPC).
  5. Broadcast. Treasury attaches the signature and broadcasts the transaction, unless you created the request with broadcast set to false.
  6. 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

StatusMeaningFinal?
pendingTreasury has recorded the request and is opening the io.sign request.No
submitted_for_signatureWaiting for your signers to approve and sign in io.sign.No
signedSigned, 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_broadcastSigned and held because you set broadcast to false. Call the broadcast endpoint to send it.No
broadcastSent to the network. Follow its on-chain status for confirmation.Yes
fulfilledA signature-only request has its signature. Nothing is broadcast.Yes
rejectedA signer declined the request in io.sign.Yes
expiredThe approval deadline passed before the threshold was met.Yes
cancelledThe request was cancelled in io.sign.Yes
failedThe 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 statusMeaning
pendingIn the network's mempool, not yet in a block.
confirmedIncluded in a block.
finalizedFinal under the network's rules. The request is settled.
failedIncluded in a block but reverted. The request becomes failed.
orphanedIts 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.


Did this page help you?