API
Migration guide

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 ServiceSafe 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 delegatePATCH /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 queueGET /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, chainId and chain_id both work.
  • The service ignores unknown body fields. A leftover origin, sender, or contractTransactionHash is dropped without an error. Check that originName and originUrl are 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
}

  • signatures is 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 safeTxHash itself 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 EOA or ETH_SIGN signature.
  • 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 by originName (up to 100 characters) and originUrl (up to 200 characters). Free text goes in notes (up to 200 characters). Other keys that you stored in the origin JSON aren't kept.
  • A nonce lower 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 safeTxHash is 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 with POST /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}/signatures and a body {"signatures": [...]}. The Safe Transaction Service took a single {"signature"}.
  • signatures takes 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 totp outside the accepted hours, returns 422.

Messages

  • Create a message with POST /api/v1/safes/{safe}/messages and a body with chainId, message (a string or an EIP-712 object), signatures, and optionally originName and originUrl.
  • signatures takes 1 through 50 entries. The Safe Transaction Service took a single signature.
  • The body has no safeAppId and no origin, and messages have no notes.
  • 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 EOA or ETH_SIGN signature. 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.

  • POST returns 201 and PATCH returns 200, both with the delegate. DELETE returns 204.
  • label is optional. The Safe Transaction Service required it. It has up to 50 characters. A PATCH with an empty label, 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 (chainId is null or left out) and for all Safes (safe is null or left out). In responses, chainId is null for a delegation that's valid on all chains.
  • A Safe Transaction Service delegate was valid on one chain. Send chainId to keep the same scope. A POST without chainId creates 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.
  • delegate and delegator can't be the same address.
  • To rename a delegate, use PATCH /api/v1/delegates. Posting an existing delegate again returns 409.
  • On DELETE, chainId and safe work as filters. A null or missing chainId matches the delegations of every chain, including the ones that are valid on all chains. A null or missing safe matches the delegations of every Safe. A value matches only the delegations stored with exactly that value. A DELETE without chainId removes the delegate on every chain.
  • To delete all the delegates of a delegator, send the zero address as delegate. chainId and safe filter this request in the same way.
  • PATCH and DELETE return 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
}

  • action is add for POST, edit for PATCH, and delete for DELETE.
  • The domain chainId and safe must match the chainId and safe of the body. A null chainId in the body is 0 in the domain, and a null safe is the zero address. The Safe Transaction Service also accepted a domain without chainId. The Safe Queue Service doesn't.
  • POST and PATCH accept only the signature of the delegator. DELETE accepts 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 preparedSignatureEip1271 of that message when it has enough confirmations. The totp must 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 safe field to the domain and the action field to the message, and the domain always needs chainId.

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 ordering parameter is replaced by nonceOrder, which accepts only asc or desc. The default is asc on GET /api/v1/multisig-transactions/queue and desc on GET /api/v1/multisig-transactions and GET /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 modified in 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, and submission_date__gte. The only filters are executed, 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/queue returns 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 safes of GET /api/v1/multisig-transactions/queue needs at least one chain ID, for example safes=0xA:1:137&safes=0xB:10. Without one, the request returns 422.
  • GET /api/v1/multisig-transactions/queue is 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 executed query parameter of GET /api/v1/multisig-transactions and GET /api/v1/safes/{safe}/multisig-transactions. GET /api/v1/multisig-transactions/queue ignores 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:
    • chainId on GET /api/v1/safes/{safe}/multisig-transactions, GET /api/v1/safes/{safe}/messages, and GET /api/v1/delegates.
    • The chain IDs inside safes on GET /api/v1/multisig-transactions and GET /api/v1/multisig-transactions/queue. GET /api/v1/multisig-transactions ignores a chainId parameter.
  • Check chainId on 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 ServiceSafe Queue Service
transactionHashtxHash
isExecutedNo field. The transaction is executed when txHash isn't null.
isSuccessfulfailed, with the opposite meaning. It's null until the transaction is executed.
submissionDatecreated
modifiedmodified. It moves forward every time a signature is added through the API.
originoriginName, originUrl, and notes
proposedByDelegateproposedBy, when proposedVia is DELEGATE
confirmations[].submissionDateconfirmations[].created, plus confirmations[].modified. Confirmations have no transactionHash.
to, gasToken, and refundReceiver, with the zero address when they aren't setto, 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 fieldWhere to get it
confirmationsRequiredThe threshold of the Safe, from GET /api/v1/safes/{address}/ of the Safe Transaction Service.
trustedNo replacement. Every proposal is signed.
dataDecodedThe Safe Decoder Service.
executionDate, blockNumber, gasUsed, fee, ethGasPrice, maxFeePerGas, maxPriorityFeePerGas, payment, signaturesThe Safe Transaction Service. See Reading data from both services.
countUniqueNonce, in the list responseNo replacement.

New transaction fields:

  • chainId: the chain of the transaction.
  • proposedVia: how the proposal was signed, one of OWNER, DELEGATE, NESTED_OWNER, or UNKNOWN. UNKNOWN is a legacy transaction with no proposer data. Treat proposedVia as 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 from proposer. For DELEGATE, proposer is the delegating owner and proposedBy the delegate. For NESTED_OWNER, proposer is the owner Safe and proposedBy the signer.
  • originName and originUrl: 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, and proposedVia, OWNER or NESTED_OWNER, are new fields.
  • The proposedBy of the Safe Transaction Service is now proposer. proposedBy is set only when it differs from proposer, which happens when the owner of an owner Safe created the message.
  • origin is replaced by originName and originUrl.
  • preparedSignature and preparedSignatureEip1271 remain. Both are null while the message has no confirmations.
  • Messages have no safeAppId.

In delegates:

  • A delegate has delegate, delegator, safe, chainId, label, created, and modified.
  • chainId is a decimal string, or null for a delegation that's valid on all chains.
  • safe is null for a delegation that's valid for all Safes, and label can be null.
  • 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, and executor are null again.

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, and executor, 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 its originName, originUrl, and notes from the Safe Queue Service. For a history page, get the Safe Queue Service records of all its transactions in one request with GET /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/batch leaves 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 trusted when 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.
  • Delegates are copied too, so a delegate created in the Safe Transaction Service can already exist in the Safe Queue Service. POST /api/v1/delegates returns 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, and DELETED_DELEGATE. It also sends NEW_CONFIRMATION for the signatures sent to its API.
  • The Safe Transaction Service keeps sending the events of on-chain data, such as EXECUTED_MULTISIG_TRANSACTION and the NEW_CONFIRMATION of an on-chain approval.

The events of the Safe Queue Service differ in these points:

  • PENDING_MULTISIG_TRANSACTION, DELETED_MULTISIG_TRANSACTION, MESSAGE_CREATED, and MESSAGE_CONFIRMATION have no timestamp field.
  • In delegate events, chainId is "0" for a delegate that's valid on all chains, expiryDateSeconds is always null, and label is an empty string when the delegate has no label and in every DELETED_DELEGATE event.
  • 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/delegates updates the label of a delegate.
  • GET /api/v1/multisig-transactions lists the transactions of several Safes on several chains in one request.
  • GET /api/v1/multisig-transactions/queue lists the pending transactions that can still be executed.
  • safes takes up to 100 values on both endpoints. More values return 422.
  • GET /api/v1/multisig-transactions/batch gets up to 100 transactions by their safeTxHash. Repeat safeTxHash for each hash. More than 100 hashes return 422.
  • The response of GET /api/v1/multisig-transactions/batch is a plain array in no particular order, without count, next, or previous. Hashes that don't match a transaction are left out instead of returning an error. Match the results by safeTxHash.
  • 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 many safes values, or a GET /api/v1/delegates request without safe, delegator, or delegate.
  • 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 limit and offset and return the same count, next, previous, and results envelope. limit defaults to 50 and accepts up to 100. The Safe Transaction Service defaulted to 100. A value above 100, limit=0, or a negative offset returns 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=desc on /queue falls back to asc, 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.
  • chainId on GET /api/v1/multisig-transactions. It's ignored, and the list covers every chain. Put the chain IDs inside safes.
  • Leftover body fields. A leftover origin, sender, contractTransactionHash, or expiryDate is dropped. Check that originName and originUrl are set.
  • Custom origin keys. Only the name, the URL, and the note of the origin are kept. Other keys of the origin JSON are lost.
  • Delegates without chainId. A POST creates a delegation that's valid on every chain, and a DELETE removes the delegate on every chain.
  • Exact chain match for delegates. GET /api/v1/delegates?delegator=0x...&chainId=N doesn't return the delegates that are valid on all chains. See the overview.
  • null addresses in responses. to, gasToken, and refundReceiver can be null. 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.
  • /batch results. They come in no particular order, and unknown hashes are left out.

Migration checklist

  1. 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.
  2. Move the chain from the URL into chainId or into safes={safe}:{chainId}, depending on the endpoint.
  3. Rename every query parameter to camel case, remove the Safe Transaction Service list filters, and remove the trailing slashes.
  4. Limit limit to 100, and expect 50 results per page by default.
  5. Proposals: send signatures as an array, remove contractTransactionHash, sender, and origin, set originName, originUrl, and notes, send numbers as integers or decimal strings, and handle 409 and 422.
  6. Confirmations: use the signatures endpoints with an array, send only signatures of owners that haven't confirmed yet, and read the response as a list of confirmations.
  7. Deletion: sign with the domain name Safe Queue Service and an EOA or ETH_SIGN signature.
  8. Messages: send chainId and signatures, replace origin with originName and originUrl, remove safeAppId, and filter lists by chain.
  9. Delegates: sign the new typed data with the safe domain field and the action field, send chainId to keep a delegation on one chain, move the delegate from the URL to the DELETE body, scope list queries by safe, delegator, or delegate, rename with PATCH, and drop the expiry date.
  10. Response parsing: accept null in to, gasToken, and refundReceiver, decimal strings for numbers, created instead of submissionDate, txHash and failed, and new values of proposedVia. Get confirmationsRequired from the Safe threshold and dataDecoded from the Safe Decoder Service.
  11. Pending queue: replace executed=false&nonce__gte=… with GET /api/v1/multisig-transactions/queue, list only the chains where each Safe is deployed, and sort by modified in your client if you need it.
  12. 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.
  13. Webhooks: accept events without timestamp, and get the details of proposals, confirmations, messages, and delegates from the Safe Queue Service.
  14. During a gradual rollout, switch the base URL and the EIP-712 typed data together.

Was this page helpful?