Coordinate Safe approvals

Configure a service or implement a coordinator. See Need Help for support.

Prerequisites: the configuration shared by all owners and a backend that preserves signed operations and confirmations. Protect access to proposal data and any service credentials.

Configure a Service

By default, the account constructs SafeTxServiceCoordinator using its chain ID, txServiceUrl and safeApiKey. Provide at least one of txServiceUrl, safeApiKey or coordinator; the default coordinator initializes API Kit on first use.

For Safe's hosted service, set only safeApiKey and use a chain in API Kit 4.0.1's network list. Use txServiceUrl for a self-hosted service or a backend proxy that adds credentials. The API key is not forwarded when a URL is set, so a hosted URL plus safeApiKey fails API Kit's key requirement.

Use an explicit service coordinator when several accounts should share it:

import { SafeTxServiceCoordinator } from '@tetherto/wdk-wallet-multisig-safe'
import { config, requiredEnv } from './safe-account.mjs'

const coordinator = new SafeTxServiceCoordinator({
  chainId: config.chainId,
  txServiceUrl: requiredEnv('SAFE_TX_SERVICE_URL')
})

In JavaScript, pass this instance in account configuration as coordinator. Beta.1's published TypeScript declarations make SafeTxServiceCoordinator incompatible with the default IMultisigCoordinator type: its service response allows missing confirmations, while the interface requires them. In TypeScript, use txServiceUrl or safeApiKey on account config to select the default coordinator without assigning an instance. Constructing the service coordinator does not make a service request. Use a backend proxy when credentials must remain private.

With this default coordinator, hosted lookups for unknown proposal or message identifiers reject with the service's error instead of returning null. A bulk lookup containing an unknown identifier rejects the whole call. See error handling before relying on nullable results.

Implement a Coordinator

A custom IMultisigCoordinator must implement six operations in the API contract. It must retain the exact operation payload, confirmations and message data expected by the Safe adapter; the generic TypeScript response types are not a complete wire schema.

1. Persist submitted proposal/message payloads without changing signed fields.
2. Return null for missing identifiers; preserve genuine backend failures as failures.
3. Attach owner confirmations and return Safe-service-compatible operation/message responses, including preparedSignature for combined messages.
4. Authenticate owners and let each signer independently review the operation before signing.

Use toJsonSafe() before JSON serialization of payloads containing bigints or byte arrays:

import { toJsonSafe } from '@tetherto/wdk-wallet-multisig-safe'
const serialized = JSON.stringify(toJsonSafe({ amount: 1000n }))

The helper turns bigints into decimal strings and byte arrays into hex strings. It does not authenticate or encrypt payloads. The account's operation-hash checks detect some mismatched payloads; they do not replace backend access controls or the owner's review screen.

Next Steps

• Usage
• Configuration
• API reference

Need Help?