Migrate from the Safe Transaction Service to the Safe Queue Service
The Safe Queue Service replaces the off-chain queue endpoints of the Safe Transaction Service: transaction proposals, signatures, messages, and delegates. This page lists what changes for an integration that calls those endpoints, and the mistakes to avoid while you move.
Endpoint mapping
The Safe Transaction Service runs one instance per chain, under https://api.safe.global/tx-service/{chain}. The Safe Queue Service serves all chains from a single base URL, https://api.safe.global/queue. The chain goes in the request body (chainId) or in the query. The query parameter that carries it depends on the endpoint: see Chain handling. The following table maps the replaced endpoints:
| Safe Transaction Service | Safe Queue Service |
|---|---|
GET /api/v2/delegates/ | GET /api/v1/delegates |
POST /api/v2/delegates/ | POST /api/v1/delegates |
POST /api/v2/delegates/ again with a new label, to rename a delegate | PATCH /api/v1/delegates. The Safe Transaction Service updated the label on a repeated POST. The Safe Queue Service returns 409 for it. |
DELETE /api/v2/delegates/{delegate_address}/ | DELETE /api/v1/delegates, with the delegate in the JSON body |
GET /api/v2/safes/{address}/multisig-transactions/ | GET /api/v1/safes/{safe}/multisig-transactions |
GET /api/v2/safes/{address}/multisig-transactions/?executed=false&nonce__gte=…&ordering=nonce, for the pending queue | GET /api/v1/multisig-transactions/queue?safes={safe}:{chainId}&nonceOrder=asc. The results are already filtered to a nonce equal to or higher than the current nonce of the Safe. |
POST /api/v2/safes/{address}/multisig-transactions/ | POST /api/v1/multisig-transactions, with safe and chainId in the body |
GET /api/v2/multisig-transactions/{safe_tx_hash}/ | GET /api/v1/multisig-transactions/{safe_tx_hash} |
DELETE /api/v2/multisig-transactions/{safe_tx_hash}/ | DELETE /api/v1/multisig-transactions/{safe_tx_hash} |
GET /api/v1/multisig-transactions/{safe_tx_hash}/confirmations/ | No equivalent. The confirmations are part of the transaction. |
POST /api/v1/multisig-transactions/{safe_tx_hash}/confirmations/ | POST /api/v1/multisig-transactions/{safe_tx_hash}/signatures |
GET /api/v1/safes/{address}/messages/ | GET /api/v1/safes/{safe}/messages |
POST /api/v1/safes/{address}/messages/ | POST /api/v1/safes/{safe}/messages |
GET /api/v1/messages/{message_hash}/ | GET /api/v1/messages/{message_hash} |
POST /api/v1/messages/{message_hash}/signatures/ | POST /api/v1/messages/{message_hash}/signatures |
Paths have no trailing slash, and each path carries its own version, /api/v1/... today.
Request changes
Query parameters
Query parameter names use camel case: safeTxHash, nonceOrder, chainId. The Safe Transaction Service names, such as safe_tx_hash or nonce__gte, don't exist.
On every endpoint, the service ignores a query parameter name that it doesn't know. A misspelled or snake case filter is dropped without an error, and the request returns 200 without that filter. For example, nonce_order=desc on GET /api/v1/multisig-transactions/queue is ignored, and the list comes in the default order, asc.
The request only fails with 422 when ignoring the name leaves a required parameter missing. For example, safe_tx_hash on GET /api/v1/multisig-transactions/batch returns 422, because safeTxHash is missing.
Check every parameter name against the Safe Queue Service reference. A misspelled filter returns results, but not the ones you asked for.
Request bodies
- Request bodies accept both camel case and snake case field names. For example,
chainIdandchain_idboth work. - The service ignores unknown body fields. A leftover
origin,sender, orcontractTransactionHashis dropped without an error. Check thatoriginNameandoriginUrlare actually set in what you send. - The exception is
nestedTransaction, which rejects unknown fields with 422.
Numbers in request bodies
chainId, nonce, value, safeTxGas, baseGas, gasPrice, and operation are integers.
- Decimal strings are also accepted, for example
"1000000000000000". - Send values above 2^53 as decimal strings. JavaScript numbers lose precision above that value.
- Hexadecimal strings, such as
"0x2a", are rejected with 422.
Transaction proposals
A proposal moves the Safe and the chain into the body, replaces sender, signature, and contractTransactionHash with a signatures array, and splits origin into separate fields.
Before, POST https://api.safe.global/tx-service/sep/api/v2/safes/0xSafe/multisig-transactions/:
_16{_16 "to": "0xRecipient",_16 "value": "1000000000000000",_16 "data": null,_16 "operation": 0,_16 "safeTxGas": "0",_16 "baseGas": "0",_16 "gasPrice": "0",_16 "gasToken": "0x0000000000000000000000000000000000000000",_16 "refundReceiver": "0x0000000000000000000000000000000000000000",_16 "nonce": 42,_16 "contractTransactionHash": "0xSafeTxHash",_16 "sender": "0xOwner",_16 "signature": "0xOwnerSignature",_16 "origin": "{\"name\":\"My dApp\",\"url\":\"https://dapp.example\"}"_16}
After, POST https://api.safe.global/queue/api/v1/multisig-transactions:
_18{_18 "chainId": 11155111,_18 "safe": "0xSafe",_18 "to": "0xRecipient",_18 "value": "1000000000000000",_18 "data": null,_18 "operation": 0,_18 "safeTxGas": "0",_18 "baseGas": "0",_18 "gasPrice": "0",_18 "gasToken": "0x0000000000000000000000000000000000000000",_18 "refundReceiver": "0x0000000000000000000000000000000000000000",_18 "nonce": 42,_18 "signatures": ["0xOwnerSignature"],_18 "originName": "My dApp",_18 "originUrl": "https://dapp.example",_18 "notes": "Payroll"_18}
signaturesis required and takes 1 through 50 entries. Unsigned proposals are rejected. If you proposed transactions only to get their decoded data for a preview, use the Safe Decoder Service instead.- The service computes the
safeTxHashitself and returns the full transaction with status 201. The request has no field for a hash computed by the client. If your client computes a different hash, the signature doesn't match an owner, and the request returns 422. The error message is about the signer, not about the hash. - The first signature decides who the proposer is. It can come from a Safe owner, a delegate of an owner, or an owner of a Safe that owns this Safe, directly or through other owner Safes, up to four levels.
- If the first signature is from an owner, every signature in the request must be from a different owner. All of them are stored as confirmations.
- A delegate, or an owner of an owner Safe, sends exactly one signature. It isn't stored as a confirmation. Owners add their confirmations afterward. An owner of an owner Safe signs with an
EOAorETH_SIGNsignature. - The returned transaction can have confirmations that the request didn't send. The service also looks for owners that already approved the hash on-chain with
approveHash, and stores a confirmation for each one that it finds. origin, a JSON string, is replaced byoriginName(up to 100 characters) andoriginUrl(up to 200 characters). Free text goes innotes(up to 200 characters). Other keys that you stored in theoriginJSON aren't kept.- A
noncelower than the current nonce of the Safe returns 422. - A Safe that the service can't find on that chain returns 422, not 404.
- A valid proposal whose
safeTxHashis already stored returns 409. This check runs after the others, so a repeated proposal whose nonce is now lower than the nonce of the Safe returns 422. On the Safe Transaction Service, posting the proposal again with a new signature added a confirmation. On the Safe Queue Service, add signatures withPOST /api/v1/multisig-transactions/{safe_tx_hash}/signatures.
A proposal can also carry a nestedTransaction: a transaction of a Safe that this Safe owns, proposed together with the approveHash or execTransaction call that acts on it. Its Safe is the proposal's to, and its chain is the proposal's chainId. It takes no signatures, because the proposal's calldata authenticates it, and it rejects unknown fields. Only an owner can sign a proposal that carries a nestedTransaction. See the "Create Multisig Transaction" endpoint in the Safe Queue Service reference for the conditions.
Signatures
- Add confirmations with
POST /api/v1/multisig-transactions/{safe_tx_hash}/signaturesand a body{"signatures": [...]}. The Safe Transaction Service took a single{"signature"}. signaturestakes up to 50 entries, each from a different owner that hasn't confirmed yet. Only owners can confirm. Delegates can't.- The request is all or nothing. If one signature is from an owner that already confirmed, the whole request returns 409 and no signature is stored. The same owner twice in one request returns 422.
- An executed transaction takes no more confirmations and returns 422.
- Messages work the same way, with
POST /api/v1/messages/{message_hash}/signatures. A message has no executed state, so it always accepts the signature of an owner that hasn't signed yet.
Deleting a pending transaction
DELETE /api/v1/multisig-transactions/{safe_tx_hash} takes a JSON body {"signature": "0x..."} and returns 204 on success.
The signature is an EIP-712 signature of a DeleteRequest. Only EOA and ETH_SIGN signature types are accepted. The typed data is the same as on the Safe Transaction Service, except for the domain name:
_25{_25 "types": {_25 "EIP712Domain": [_25 { "name": "name", "type": "string" },_25 { "name": "version", "type": "string" },_25 { "name": "chainId", "type": "uint256" },_25 { "name": "verifyingContract", "type": "address" }_25 ],_25 "DeleteRequest": [_25 { "name": "safeTxHash", "type": "bytes32" },_25 { "name": "totp", "type": "uint256" }_25 ]_25 },_25 "primaryType": "DeleteRequest",_25 "domain": {_25 "name": "Safe Queue Service",_25 "version": "1.0",_25 "chainId": 11155111,_25 "verifyingContract": "0xSafe"_25 },_25 "message": {_25 "safeTxHash": "0xSafeTxHash",_25 "totp": 494213_25 }_25}
totp is the Unix time in seconds divided by 3600, rounded down. The service accepts the value of the current hour and of the previous hour.
These signers can delete a pending transaction:
- The proposer. For a proposal made by a delegate, the proposer is the delegating owner.
- The delegate that proposed it, while it's still a delegate of the proposer.
- The account that signed the proposal as an owner of an owner Safe, while it still owns this Safe, directly or through any owner Safe.
Other results:
- A hash that doesn't exist returns 404.
- An executed transaction, or a legacy transaction with no proposer data, can't be deleted and returns 422.
- A signer that isn't in the list, or a
totpoutside the accepted hours, returns 422.
Messages
- Create a message with
POST /api/v1/safes/{safe}/messagesand a body withchainId,message(a string or an EIP-712 object),signatures, and optionallyoriginNameandoriginUrl. signaturestakes 1 through 50 entries. The Safe Transaction Service took a singlesignature.- The body has no
safeAppIdand noorigin, and messages have nonotes. - A Safe owner, or an owner of a Safe that owns this Safe, can create a message. Delegates can't, and a delegate signature returns 422.
- An owner of an owner Safe sends exactly one
EOAorETH_SIGNsignature. It isn't stored as a confirmation, so the message starts with no confirmations.
Delegates
POST, PATCH, and DELETE all go to /api/v1/delegates, with every field in the JSON body: delegate, delegator, signature, and the optional chainId and safe. POST and PATCH also take an optional label.
POSTreturns 201 andPATCHreturns 200, both with the delegate.DELETEreturns 204.labelis optional. The Safe Transaction Service required it. It has up to 50 characters. APATCHwith an emptylabel, or without one, removes the label.- Delegates have no expiry date. The service ignores
expiryDate, so a delegation lasts until it's deleted. - A delegation can be valid on all chains (
chainIdisnullor left out) and for all Safes (safeisnullor left out). In responses,chainIdisnullfor a delegation that's valid on all chains. - A Safe Transaction Service delegate was valid on one chain. Send
chainIdto keep the same scope. APOSTwithoutchainIdcreates a delegation that's valid on every chain. - The service doesn't check that the delegator owns the Safe when the delegate is created. The Safe Transaction Service did. The delegator must be a current owner when the delegate proposes a transaction.
delegateanddelegatorcan't be the same address.- To rename a delegate, use
PATCH /api/v1/delegates. Posting an existing delegate again returns 409. - On
DELETE,chainIdandsafework as filters. Anullor missingchainIdmatches the delegations of every chain, including the ones that are valid on all chains. Anullor missingsafematches the delegations of every Safe. A value matches only the delegations stored with exactly that value. ADELETEwithoutchainIdremoves the delegate on every chain. - To delete all the delegates of a delegator, send the zero address as
delegate.chainIdandsafefilter this request in the same way. PATCHandDELETEreturn 404 when there is nothing to update or delete.- When an owner is removed from a Safe, the service deletes the delegates of that owner that are scoped to exactly that Safe and chain. Delegations that are valid on all chains or for all Safes stay.
The delegator signs EIP-712 typed data. Compared with the Safe Transaction Service, the domain name is Safe Queue Service, the domain adds a safe field and always has chainId, and the message adds an action field:
_27{_27 "types": {_27 "EIP712Domain": [_27 { "name": "name", "type": "string" },_27 { "name": "version", "type": "string" },_27 { "name": "chainId", "type": "uint256" },_27 { "name": "safe", "type": "address" }_27 ],_27 "Delegate": [_27 { "name": "delegateAddress", "type": "address" },_27 { "name": "totp", "type": "uint256" },_27 { "name": "action", "type": "string" }_27 ]_27 },_27 "primaryType": "Delegate",_27 "domain": {_27 "name": "Safe Queue Service",_27 "version": "1.0",_27 "chainId": 11155111,_27 "safe": "0x0000000000000000000000000000000000000000"_27 },_27 "message": {_27 "delegateAddress": "0xDelegate",_27 "totp": 494213,_27 "action": "add"_27 }_27}
actionisaddforPOST,editforPATCH, anddeleteforDELETE.- The domain
chainIdandsafemust match thechainIdandsafeof the body. AnullchainIdin the body is0in the domain, and anullsafeis the zero address. The Safe Transaction Service also accepted a domain withoutchainId. The Safe Queue Service doesn't. POSTandPATCHaccept only the signature of the delegator.DELETEaccepts the signature of the delegator or of the delegate.- A Safe can be a delegator with an EIP-1271 signature. The owners of the Safe sign a Safe message whose content is this typed data, and the request sends the
preparedSignatureEip1271of that message when it has enough confirmations. Thetotpmust still be valid when the request is sent. - An EIP-1271 signature needs a
chainId. It isn't accepted for a delegation that's valid on all chains.
Gradual rollout
The deletion and delegate signatures include the service name in the EIP-712 domain: Safe Transaction Service or Safe Queue Service. A signature built for one service fails on the other.
- For a transaction deletion, only the domain name differs.
- For delegates, the typed data differs too: the Safe Queue Service adds the
safefield to the domain and theactionfield to the message, and the domain always needschainId.
If you migrate gradually, for example per chain or per environment, pick the typed data with the same switch that picks the base URL.
Listing and ordering
- The
orderingparameter is replaced bynonceOrder, which accepts onlyascordesc. The default isasconGET /api/v1/multisig-transactions/queueanddesconGET /api/v1/multisig-transactionsandGET /api/v1/safes/{safe}/multisig-transactions. - You can't sort by creation date or by modification date. To sort by last activity, get every page and sort on
modifiedin your client. - The list filters of the Safe Transaction Service are gone, and the service ignores them without an error. Examples are
nonce,nonce__gte,modified__gt,to,value,trusted,has_confirmations,execution_date__gte, andsubmission_date__gte. The only filters areexecuted, the chain, and the pagination. To find the proposals at a given nonce, get every page and filter in your client. GET /api/v1/multisig-transactions/queuereturns only transactions that aren't executed and whose nonce is equal to or higher than the current nonce of the Safe. You don't need to read the nonce of the Safe first.- Every Safe in the
safesofGET /api/v1/multisig-transactions/queueneeds at least one chain ID, for examplesafes=0xA:1:137&safes=0xB:10. Without one, the request returns 422. GET /api/v1/multisig-transactions/queueis all or nothing. If the service can't find one Safe on one of its chains, the whole request returns 422. List only the chains where each Safe is deployed.- To filter by execution state, use the
executedquery parameter ofGET /api/v1/multisig-transactionsandGET /api/v1/safes/{safe}/multisig-transactions.GET /api/v1/multisig-transactions/queueignores it and always returns pending transactions. - Messages have no ordering parameter. They come newest first, by creation date.
- Lists without a chain filter return results from every chain. The chain filter depends on the endpoint:
chainIdonGET /api/v1/safes/{safe}/multisig-transactions,GET /api/v1/safes/{safe}/messages, andGET /api/v1/delegates.- The chain IDs inside
safesonGET /api/v1/multisig-transactionsandGET /api/v1/multisig-transactions/queue.GET /api/v1/multisig-transactionsignores achainIdparameter.
- Check
chainIdon each result.
Response changes
In a transaction, chainId, nonce, value, safeTxGas, baseGas, and gasPrice are decimal strings. chainId is a new field. The v2 endpoints of the Safe Transaction Service already returned the other five as strings. These fields change:
| Safe Transaction Service | Safe Queue Service |
|---|---|
transactionHash | txHash |
isExecuted | No field. The transaction is executed when txHash isn't null. |
isSuccessful | failed, with the opposite meaning. It's null until the transaction is executed. |
submissionDate | created |
modified | modified. It moves forward every time a signature is added through the API. |
origin | originName, originUrl, and notes |
proposedByDelegate | proposedBy, when proposedVia is DELEGATE |
confirmations[].submissionDate | confirmations[].created, plus confirmations[].modified. Confirmations have no transactionHash. |
to, gasToken, and refundReceiver, with the zero address when they aren't set | to, gasToken, and refundReceiver, with null when they aren't set |
to, gasToken, and refundReceiver can be null. If your client validates responses with a strict address schema, it rejects the whole page. Use the zero address in their place when you compute the safeTxHash.
These fields are gone. Get them elsewhere:
| Safe Transaction Service field | Where to get it |
|---|---|
confirmationsRequired | The threshold of the Safe, from GET /api/v1/safes/{address}/ of the Safe Transaction Service. |
trusted | No replacement. Every proposal is signed. |
dataDecoded | The Safe Decoder Service. |
executionDate, blockNumber, gasUsed, fee, ethGasPrice, maxFeePerGas, maxPriorityFeePerGas, payment, signatures | The Safe Transaction Service. See Reading data from both services. |
countUniqueNonce, in the list response | No replacement. |
New transaction fields:
chainId: the chain of the transaction.proposedVia: how the proposal was signed, one ofOWNER,DELEGATE,NESTED_OWNER, orUNKNOWN.UNKNOWNis a legacy transaction with no proposer data. TreatproposedViaas an open list of values: a client that only accepts the values it knows breaks when a new one appears.proposedBy: the address that signed the proposal, when it differs fromproposer. ForDELEGATE,proposeris the delegating owner andproposedBythe delegate. ForNESTED_OWNER,proposeris the owner Safe andproposedBythe signer.originNameandoriginUrl: the name and URL of the app that sent the proposal.notes: free text sent with the proposal.
In messages:
- Creating a message returns 201 with the full message. The Safe Transaction Service returned an empty body.
chainId, a decimal string, andproposedVia,OWNERorNESTED_OWNER, are new fields.- The
proposedByof the Safe Transaction Service is nowproposer.proposedByis set only when it differs fromproposer, which happens when the owner of an owner Safe created the message. originis replaced byoriginNameandoriginUrl.preparedSignatureandpreparedSignatureEip1271remain. Both arenullwhile the message has no confirmations.- Messages have no
safeAppId.
In delegates:
- A delegate has
delegate,delegator,safe,chainId,label,created, andmodified. chainIdis a decimal string, ornullfor a delegation that's valid on all chains.safeisnullfor a delegation that's valid for all Safes, andlabelcan benull.- Delegates have no
expiryDate.
The signature endpoints of transactions and messages return 201 and an array with the new confirmations, not the full transaction or message. Get the transaction or message again to read its full state.
Changes without a request
The service changes stored data on its own in two cases:
- When an owner is removed from a Safe, the service deletes the confirmations of that owner from the pending transactions and from the messages of the Safe. It also deletes the delegates of that owner that are scoped to exactly that Safe and chain.
- After a chain reorganization, an executed transaction can go back to pending. Its
txHash,failed, andexecutorarenullagain.
Reading data from both services
- Read pending data from the Safe Queue Service, and execution details from the Safe Transaction Service. The Safe Queue Service record of an executed transaction has
txHash,failed, andexecutor, but no other execution metadata. - For an executed transaction, get its execution details from
GET /api/v2/multisig-transactions/{safe_tx_hash}/of the Safe Transaction Service, and itsoriginName,originUrl, andnotesfrom the Safe Queue Service. For a history page, get the Safe Queue Service records of all its transactions in one request withGET /api/v1/multisig-transactions/batch. - The Safe Queue Service has no record of a transaction that was executed without being proposed.
GET /api/v1/multisig-transactions/batchleaves those hashes out. - While both services run, each one copies what is written to the other: transaction proposals, confirmations, deletions, messages, and delegates. The copy usually takes a few seconds, so the other service can return 404 right after a write. Read back from the service that you wrote to.
- The copy doesn't keep everything:
- From a Safe Transaction Service
origin, only the name, the URL, and the note are kept. - A proposal that the Safe Transaction Service doesn't mark as
trustedwhen it's created isn't copied, even if it's confirmed later. - A Safe Transaction Service delegate with an expiry date isn't copied. Create it again in the Safe Queue Service.
- From a Safe Transaction Service
- Delegates are copied too, so a delegate created in the Safe Transaction Service can already exist in the Safe Queue Service.
POST /api/v1/delegatesreturns 409 for it.
Events and webhooks
Webhooks keep the same event types. Each write is announced once, by the service that received it:
- The Safe Queue Service sends
PENDING_MULTISIG_TRANSACTION,DELETED_MULTISIG_TRANSACTION,MESSAGE_CREATED,MESSAGE_CONFIRMATION,NEW_DELEGATE,UPDATED_DELEGATE, andDELETED_DELEGATE. It also sendsNEW_CONFIRMATIONfor the signatures sent to its API. - The Safe Transaction Service keeps sending the events of on-chain data, such as
EXECUTED_MULTISIG_TRANSACTIONand theNEW_CONFIRMATIONof an on-chain approval.
The events of the Safe Queue Service differ in these points:
PENDING_MULTISIG_TRANSACTION,DELETED_MULTISIG_TRANSACTION,MESSAGE_CREATED, andMESSAGE_CONFIRMATIONhave notimestampfield.- In delegate events,
chainIdis"0"for a delegate that's valid on all chains,expiryDateSecondsis alwaysnull, andlabelis an empty string when the delegate has no label and in everyDELETED_DELEGATEevent. - A webhook that filters by chain doesn't receive the events of a delegate that's valid on all chains.
After an event about a proposal, a confirmation, a message, or a delegate, get the details from the Safe Queue Service.
New endpoints
PATCH /api/v1/delegatesupdates the label of a delegate.GET /api/v1/multisig-transactionslists the transactions of several Safes on several chains in one request.GET /api/v1/multisig-transactions/queuelists the pending transactions that can still be executed.safestakes up to 100 values on both endpoints. More values return 422.GET /api/v1/multisig-transactions/batchgets up to 100 transactions by theirsafeTxHash. RepeatsafeTxHashfor each hash. More than 100 hashes return 422.- The response of
GET /api/v1/multisig-transactions/batchis a plain array in no particular order, withoutcount,next, orprevious. Hashes that don't match a transaction are left out instead of returning an error. Match the results bysafeTxHash. - A request with 100 hashes gets close to the common 8 KB limit for a request line, so send fewer hashes per request if a proxy on your path is stricter.
- A transaction proposal can carry a
nestedTransaction. See Transaction proposals.
Errors and pagination
- The Safe Transaction Service returned 400 for signature and authorization failures in confirmations, messages, delegates, and transaction deletions. Its proposal endpoint already returned 422. The Safe Queue Service returns 422 for all of them.
- 422 responses have two body shapes:
{"detail": [{"loc": ..., "msg": ..., "type": ...}]}, a list, for most missing or malformed fields and parameters.{"detail": "..."}, a string, for every other rejection, such as an invalid signature, a signer that isn't allowed, a Safe that isn't found, too manysafesvalues, or aGET /api/v1/delegatesrequest withoutsafe,delegator, ordelegate.
- Duplicates return 409: a transaction or message hash that already exists, an owner that already confirmed, or a delegate that already exists for the same delegator, chain, and Safe. The Safe Transaction Service accepted a repeated transaction confirmation, and returned 400 for a duplicate message.
- Lists take
limitandoffsetand return the samecount,next,previous, andresultsenvelope.limitdefaults to 50 and accepts up to 100. The Safe Transaction Service defaulted to 100. A value above 100,limit=0, or a negativeoffsetreturns 422, so check these values in your client. - The endpoints that read the Safe return 503 when the service can't get the information of the chain or of the Safe. That happens on a chain that the service doesn't support, and when that information is temporarily unavailable. The status alone doesn't tell the two cases apart.
- These endpoints read the Safe: proposing a transaction,
GET /api/v1/multisig-transactions/queue, proposing a message, and adding signatures to a transaction or to a message. Deleting a transaction reads the Safe only for a proposal made by an owner of an owner Safe. - The other list endpoints don't check the chain. With a chain that the service doesn't support, they return 200 with empty results. Requests by hash take no chain.
- Delegate requests with an EOA signature have no chain check. Delegate requests with an EIP-1271 signature return 503 on a chain that the service doesn't support.
What stays in the Safe Transaction Service
The Safe Transaction Service keeps serving the data it indexes from the chain: the history of all executed transactions, including incoming transfers and module transactions, balances, Safe information, ERC-4337 Safe operations, and gas estimations. The Safe Queue Service only returns the multisig transactions that were proposed off-chain, pending or executed. A multisig transaction that was executed without a proposal is only in the Safe Transaction Service. See the Safe Transaction Service overview.
Common pitfalls
These mistakes return no error, so they're easy to miss:
- Unknown query parameters. A snake case or misspelled name is ignored.
nonce_order=descon/queuefalls back toasc, so a query for the highest nonce returns the lowest one. - Safe Transaction Service filters.
modified__gt,nonce__gte, and the other list filters are ignored. The request returns the full list. chainIdonGET /api/v1/multisig-transactions. It's ignored, and the list covers every chain. Put the chain IDs insidesafes.- Leftover body fields. A leftover
origin,sender,contractTransactionHash, orexpiryDateis dropped. Check thatoriginNameandoriginUrlare set. - Custom origin keys. Only the name, the URL, and the note of the origin are kept. Other keys of the
originJSON are lost. - Delegates without
chainId. APOSTcreates a delegation that's valid on every chain, and aDELETEremoves the delegate on every chain. - Exact chain match for delegates.
GET /api/v1/delegates?delegator=0x...&chainId=Ndoesn't return the delegates that are valid on all chains. See the overview. nulladdresses in responses.to,gasToken, andrefundReceivercan benull. A strict address schema rejects the whole page.- Page size. The default page has 50 results, not 100.
- Signature responses. The signature endpoints return the new confirmations, not the transaction or message.
/batchresults. They come in no particular order, and unknown hashes are left out.
Migration checklist
- Send proposal, signature, deletion, message, and delegate requests to
https://api.safe.global/queue. Keep reading history, balances, and Safe information from the Safe Transaction Service. - Move the chain from the URL into
chainIdor intosafes={safe}:{chainId}, depending on the endpoint. - Rename every query parameter to camel case, remove the Safe Transaction Service list filters, and remove the trailing slashes.
- Limit
limitto 100, and expect 50 results per page by default. - Proposals: send
signaturesas an array, removecontractTransactionHash,sender, andorigin, setoriginName,originUrl, andnotes, send numbers as integers or decimal strings, and handle 409 and 422. - Confirmations: use the
signaturesendpoints with an array, send only signatures of owners that haven't confirmed yet, and read the response as a list of confirmations. - Deletion: sign with the domain name
Safe Queue Serviceand anEOAorETH_SIGNsignature. - Messages: send
chainIdandsignatures, replaceoriginwithoriginNameandoriginUrl, removesafeAppId, and filter lists by chain. - Delegates: sign the new typed data with the
safedomain field and theactionfield, sendchainIdto keep a delegation on one chain, move the delegate from the URL to theDELETEbody, scope list queries bysafe,delegator, ordelegate, rename withPATCH, and drop the expiry date. - Response parsing: accept
nullinto,gasToken, andrefundReceiver, decimal strings for numbers,createdinstead ofsubmissionDate,txHashandfailed, and new values ofproposedVia. GetconfirmationsRequiredfrom the Safe threshold anddataDecodedfrom the Safe Decoder Service. - Pending queue: replace
executed=false&nonce__gte=…withGET /api/v1/multisig-transactions/queue, list only the chains where each Safe is deployed, and sort bymodifiedin your client if you need it. - Errors: expect 422 instead of 400 for signature and authorization failures, handle both shapes of
detail, expect 409 for duplicates, and treat 503 as possibly temporary. - Webhooks: accept events without
timestamp, and get the details of proposals, confirmations, messages, and delegates from the Safe Queue Service. - During a gradual rollout, switch the base URL and the EIP-712 typed data together.