# Migrate from the Safe Transaction Service to the Safe Queue Service

The [Safe Queue Service](./safe-queue-service-overview.mdx) 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](./safe-queue-service-overview.mdx#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](./safe-queue-service-reference.mdx). 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/`:

```json
{
  "to": "0xRecipient",
  "value": "1000000000000000",
  "data": null,
  "operation": 0,
  "safeTxGas": "0",
  "baseGas": "0",
  "gasPrice": "0",
  "gasToken": "0x0000000000000000000000000000000000000000",
  "refundReceiver": "0x0000000000000000000000000000000000000000",
  "nonce": 42,
  "contractTransactionHash": "0xSafeTxHash",
  "sender": "0xOwner",
  "signature": "0xOwnerSignature",
  "origin": "{\"name\":\"My dApp\",\"url\":\"https://dapp.example\"}"
}
```

After, `POST https://api.safe.global/queue/api/v1/multisig-transactions`:

```json
{
  "chainId": 11155111,
  "safe": "0xSafe",
  "to": "0xRecipient",
  "value": "1000000000000000",
  "data": null,
  "operation": 0,
  "safeTxGas": "0",
  "baseGas": "0",
  "gasPrice": "0",
  "gasToken": "0x0000000000000000000000000000000000000000",
  "refundReceiver": "0x0000000000000000000000000000000000000000",
  "nonce": 42,
  "signatures": ["0xOwnerSignature"],
  "originName": "My dApp",
  "originUrl": "https://dapp.example",
  "notes": "Payroll"
}
```

- `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](./safe-decoder-service-overview.mdx) 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](./safe-queue-service-reference.mdx) 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:

```json
{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" },
      { "name": "verifyingContract", "type": "address" }
    ],
    "DeleteRequest": [
      { "name": "safeTxHash", "type": "bytes32" },
      { "name": "totp", "type": "uint256" }
    ]
  },
  "primaryType": "DeleteRequest",
  "domain": {
    "name": "Safe Queue Service",
    "version": "1.0",
    "chainId": 11155111,
    "verifyingContract": "0xSafe"
  },
  "message": {
    "safeTxHash": "0xSafeTxHash",
    "totp": 494213
  }
}
```

`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:

```json
{
  "types": {
    "EIP712Domain": [
      { "name": "name", "type": "string" },
      { "name": "version", "type": "string" },
      { "name": "chainId", "type": "uint256" },
      { "name": "safe", "type": "address" }
    ],
    "Delegate": [
      { "name": "delegateAddress", "type": "address" },
      { "name": "totp", "type": "uint256" },
      { "name": "action", "type": "string" }
    ]
  },
  "primaryType": "Delegate",
  "domain": {
    "name": "Safe Queue Service",
    "version": "1.0",
    "chainId": 11155111,
    "safe": "0x0000000000000000000000000000000000000000"
  },
  "message": {
    "delegateAddress": "0xDelegate",
    "totp": 494213,
    "action": "add"
  }
}
```

- `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 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](./safe-decoder-service-overview.mdx). |
| `executionDate`, `blockNumber`, `gasUsed`, `fee`, `ethGasPrice`, `maxFeePerGas`, `maxPriorityFeePerGas`, `payment`, `signatures` | The Safe Transaction Service. See [Reading data from both services](#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 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](./webhooks-overview.mdx) 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](#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](./transaction-service-overview.mdx).

## 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](./safe-queue-service-overview.mdx#chain-handling).
- **`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.
