API
Overview

Safe Queue Service overview

Safe Queue Service is a REST API that stores the off-chain data of Safe accounts: multisig transaction proposals and their signatures, off-chain messages, and delegates. One service covers all supported chains. It replaces the off-chain queue endpoints of the Safe Transaction Service. To move an integration from those endpoints, see the migration guide.

What it is

Owners use the Safe Queue Service to propose a transaction, collect the signatures of the other owners, and share signed messages. The service doesn't execute transactions. Execution happens on-chain through the Safe contract.

Base URL and versioning

  • The base URL is https://api.safe.global/queue.
  • Each endpoint path carries its own version, /api/v1/... today. For example, https://api.safe.global/queue/api/v1/multisig-transactions. A breaking change to an endpoint ships as a new version of that endpoint, such as /api/v2/..., next to the other endpoints.
  • Paths have no trailing slash.
  • The chain is never part of the path. See Chain handling.

API key

Requests use an API key, like the other Safe APIs. To get a key and send it, see API Keys & Authentication.

Who can sign a request

Write requests carry signatures that decide who can change the queue of a Safe. These signatures are independent of the API key.

ActionWho can sign
Propose a transactionA Safe owner, a delegate of an owner, or an owner of a Safe that owns this Safe
Confirm a transaction or a messageSafe owners
Propose a messageA Safe owner, or an owner of a Safe that owns this Safe. Delegates can't propose messages.
Delete a pending transactionThe proposer, the delegate that proposed it while it's still a delegate, or the account that proposed it as an owner of an owner Safe while it still owns this Safe, directly or through any owner Safe. Only EOA and ETH_SIGN signatures are accepted.
Add or edit a delegateThe delegator. A Safe can be a delegator with an EIP-1271 signature, but only for a delegation with a chainId.
Delete a delegateThe delegator or the delegate

When a delegate proposes a transaction, send the delegate's signature alone. Owners add their confirmations afterward.

Delegate changes and transaction deletions use EIP-712 (opens in a new tab) typed data:

  • The domain name is Safe Queue Service and the version is 1.0.
  • The message contains a time-based one-time password (TOTP): the Unix time in seconds divided by 3600, rounded down. It changes every hour.
  • The service accepts the TOTP of the current hour and of the previous hour.

Delegate signatures made for the Safe Transaction Service aren't valid in the Safe Queue Service. The delegate typed data adds a safe field to the domain and an action field to the message, with the value add, edit, or delete. The domain chainId is 0 for a delegate that's valid on all chains, and safe is the zero address for a delegate that's valid for all Safes.

Chain handling

The chain is never part of the path. Each endpoint takes it in a different way.

EndpointChain
POST /api/v1/multisig-transactionschainId is required in the body.
POST /api/v1/safes/{safe}/messageschainId is required in the body.
GET /api/v1/safes/{safe}/multisig-transactions, GET /api/v1/safes/{safe}/messageschainId is an optional query filter. Without it, the list covers all chains.
GET /api/v1/multisig-transactionsEach safes value has the format address[:chainId...], for example 0xABC...:1:137. Repeat safes for each Safe, up to 100 values. A Safe without chain IDs returns results from all its chains.
GET /api/v1/multisig-transactions/queueSame safes format, but every Safe needs at least one chain ID. Without one, the request fails with 422.
GET /api/v1/multisig-transactions/{safe_tx_hash}, GET /api/v1/multisig-transactions/batch, GET /api/v1/messages/{message_hash}No chain. The hash identifies the transaction or message.
GET /api/v1/delegateschainId is an optional filter. It only narrows a query by safe, delegator, or delegate and can't be used on its own. It's an exact match, so it doesn't return delegates that are valid on all chains. chainId=0 is treated as no filter. To get the delegates that are valid on chain N, query by safe, delegator, or delegate without chainId, and keep the results whose chainId is null or N. A safe filter only returns delegations scoped to exactly that Safe, not delegations valid for all Safes. Query by delegator or delegate to get those. When a delegate proposes a transaction, delegations valid on all chains and for all Safes are accepted.

The supported chains come from the Safe Config Service. No endpoint lists them. On a chain that the service doesn't support, the endpoints that read the Safe, such as proposing a transaction or a message and GET /api/v1/multisig-transactions/queue, return 503 because the Safe information is unavailable. The same 503 is returned when chain information is temporarily unavailable. The other list endpoints don't check the chain: with a chain that the service doesn't support, they return 200 with empty results. On the endpoints that read the Safe, a Safe that the service can't find on a supported chain returns 422. See the migration guide for details.

Resources

Was this page helpful?