DEV Community: doncesarts

I Stopped Relying on the CowSwap UI and Built a CowSwap CLI Instead

doncesarts — Fri, 11 Sep 2026 13:34:36 +0000

If your trading flow depends on uptime, precision, and repeatability, a web UI is useful but not enough.

I use CowSwap regularly, but the UI has had the following issues:

frontend downtime (Annoying)
a compromised domain incident that redirected to phishing content(Cow.fi Domain Hijack)
lack of slippage price control (see Trader lost $50 million in March 2026)
missing order types for my strategy (especially buy/sell ladders)
no native way to define relative limit entries (for example, X% from market)
occasional bad quotes on thin liquidity pairs
UI crashing, I have fixed it with these PRs
- fix: order parsing when executed amounts are zero
- fix: getAppDataHooks Crash when metadata is undefined

So I built a TypeScript CLI on top of the CowSwap SDK to place orders with guardrails, even when the frontend is unavailable. The repository is here.

Try it yourself

git clone https://github.com/doncesarts/cowswap-cli
cd cowswap-cli
npm install

What I wanted

New type of orders
- Market sell / buy with explicit slippage.
- Sell/Buy ladders orders with relative price offsets around the current market price.
- Limit fixed-price limit orders.
Refresh local token registries from CowSwap and CoinGecko
- Specify address or symbol for tokens when the symbol is unavailable
- It downloads from trusted sources like CowSwap and CoinGecko the information of tokens, i.e., address - symbol so it can be used across the CLI commands.
- You can also add your custom registry file as a JSON if you only want to trust on your file.
Price quote protection
- Whenever executing an order it quotes the price on cowSwap and compares it with coingecko prices, if there is a significant discrepancy, it warns the user before executing the trade, and then its up to you to confirm it manually. So having at least another source of prices gives me more confidence in the accuracy of the trade.
Fallback path for order execution
- If the CowSwap frontend is unavailable, the CLI provides a reliable alternative to place orders directly through the SDK.
Automation-friendly
- The CLI is designed to be scriptable and easily integrated, in my case i created a Makefile to ease common trading tasks, such as placing orders in different chains based on different "profiles" or wallets.

The architecture

A visual representation of how the CLI processes commands before interacting with the CoW Protocol.

CLI arguments
     │
     ▼
Command parser
     │
     ▼
Validation / token resolution
     │
     ▼
Price + safety checks
     │
     ▼
Order construction
     │
     ▼
CoW SDK
     │
     ├── quote / order API
     │
     └── wallet signing
             │
             ▼
        CoW Protocol

Example of the cli commands.

# Market buy  with explicit slippage (Buy 0.5 WETH for USDC)
npm run buy-market -- --buy-token WETH --sell-token USDC --amount 0.5 --slippage 0.5

# Sell ladder with relative price offsets above market
npm run sell-ladder -- --sell-token WETH --buy-token USDC --amount 2 --percentages "1,3,5,8"

# Fixed-price limit sell (buy-price set the price on buy token value, sell-price set the price on sell token value)
# Example: Sell 1 WETH for USDC at a fixed buy price of 4200 USDC
npm run sell-limit -- --sell-token WETH --buy-token USDC --amount 1 --buy-price 4200

# Resolve token by address if symbol is unavailable
npm run token-info -- --token 0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --network mainnet

# Refresh CowSwap + CoinGecko registries locally
npm run update-tokens-registry

That gives me a fallback path for order execution, plus a cleaner base for automation.
You can use it passing a private key or a ledger path (recommended).

Building the CLI

1) Commands are thin, typed, and strategy-focused

Each CLI command maps flags into a typed executor. The command surface is simple, and validation/execution complexity lives in shared utilities.

program
  .command('sell-ladder')
  .requiredOption('--sell-token <symbol>')
  .requiredOption('--amount <amount>')
  .requiredOption('--percentages <percentages>')
  .option('--buy-token <symbol>', 'USDC')
  .option('--ledger-path <path>')
  .action(async (options) => executeSellLadderCommand(options));

Why this matters:

Inputs look like trading intent, not protocol internals
Flags stay consistent across order types
Execution logic stays maintainable

2) Safety checks are in the execution path, not optional

Before placing orders, the shared command flow validates inputs, resolves token/network context, checks pricing, and asks for confirmation.

const confirmed = await checkPriceAndConfirm(
  orderKind,
  validated.buyToken,
  validated.sellToken,
  networkConfig.chainId,
  amountPerOrder,
  marketPrice,
);

if (!confirmed) {
  process.exit(0);
}

Why this matters:

Price sanity checks happen before submission
You reduce accidental execution from stale or outlier quotes
Confirmation is explicit when discrepancies on source prices occur.
Even if private key is supported do not use it for production trading; prefer the ledger-based signing flow for security.

3) Sell ladders and market-relative logic are first-class

Sell ladder orders use percentage offsets above market (--percentages "1,3,5") and split the total amount across levels.

If you want a single market-relative limit order, a practical trick is using a one-level ladder.

Solving Real Gaps From the UI Path

Frontend reliability risk: CLI gives an alternate execution interface.
Missing strategy primitives: Sell ladders and relative offsets are available.
Liquidity quote risk: Extra sanity checks before order submission.
Token availability gaps: Symbol and address-based resolution supported.
Security posture: Ledger-based signing flow supported.

Why Intermediate Developers Should Care

If you already use TypeScript and trade on-chain, this pattern gives you immediate leverage:

reproducible execution
scriptable strategy workflows
less dependency on frontend state
easier path from manual trading to automation

References

For more technical details and usage examples, check out the repository: https://github.com/doncesarts/cowswap-cli
CowSwap SDK docs: https://docs.cow.fi/cow-protocol/reference/sdks/cow-sdk
CowSwap app: https://swap.cow.fi/
Domain incident statement: https://x.com/CoWSwap/status/2044924940886163780
Trade lost $50 million statement: https://x.com/CoWSwap/status/2032959076502581623
UI fix PR context:
- fix: order parsing when executed amounts are zero
- fix: getAppDataHooks Crash when metadata is undefined

How to Build a Gnosis Safe Module: Minimal Example in Solidity

doncesarts — Sat, 14 Mar 2026 07:34:08 +0000

If you have read Safe docs and still felt stuck building your first module it is not a surprise, the official documentation is good at definitions and use cases, but the examples are just too complex for a practical grasp of the mechanics.

The Core Safe Module Mental Model

A Safe module is a contract that the Safe owners explicitly authorize.

After it is enabled, that module can request Safe to execute transactions through the module execution path.

The important part: The transaction executes from the Safe context.

That means the call spends Safe funds and uses Safe permissions, not module funds.

Modules are extensions with unlimited access to a Safe that can be added to a Safe by its owners.
⚠️ WARNING: Modules are a security risk since they can execute arbitrary transactions, so only trusted and audited modules should be added to a Safe. A malicious module can completely takeover a Safe.

Minimal flow:

Safe owners enable module see
module prepares target call
module calls Safe.execTransactionFromModule(...)
Safe verifies module is enabled
Safe executes call as Safe account

That is why modules can execute on behalf of a Gnosis Safe.

The Minimal Example: StipendModule

A gnosis safe wallet multisig needs to send a given amount of tokens to a recipient every X weeks.

Without a module, every period usually means:

propose the same transfer again
collect signatures again
repeat forever

That is operationally expensive and error-prone.

With a module, you write the policy once, then trigger execution when due.

Full source in this git StipendModule.sol

Module Snipped

contract StipendModule {
    address public immutable safeWallet;
    address public immutable token;
    address public immutable recipient;
    uint256 public lastExecuted;
    uint256 public immutable amount;
    uint256 public constant interval = 4 weeks;

    error MultiSendNotConfigured();
    error ZeroAddress();
    error ZeroAmount();
    error PrematureExecution(uint256 currentTime, uint256 nextAllowedTime);

    constructor(address _safeWallet, address _token, address _recipient, uint256 _amount) {
        if (_safeWallet == address(0)) revert ZeroAddress();
        if (_token == address(0)) revert ZeroAddress();
        if (_recipient == address(0)) revert ZeroAddress();
        if (_amount == 0) revert ZeroAmount();
        safeWallet = _safeWallet;
        token = _token;
        recipient = _recipient;
        amount = _amount;
        lastExecuted = block.timestamp;
    }

    /**
     * @notice  Execute a call via the Safe contract
     * @param to    Destination address to call
     * @param data  Data payload of the transaction
     * @return success bool for success
     */
    function _execCallFromModule(address to, bytes memory data)
        internal
        virtual
        returns (bool success)
    {
        IModuleManager safe = IModuleManager(safeWallet);

        success = safe.execTransactionFromModule({
            to: to, value: 0, data: data, operation: Enum.Operation.Call
        });
        require(success, "!success");
        return success;
    }

    function stipend() external {
        if (block.timestamp < lastExecuted + interval) {
            revert PrematureExecution(block.timestamp, lastExecuted + interval);
        }
        bytes memory data = abi.encodeWithSignature("transfer(address,uint256)", recipient, amount);
        lastExecuted = block.timestamp;
        _execCallFromModule(token, data);
    }

What it stores:

safeWallet
token
recipient
amount
lastExecuted
interval = 4 weeks

What stipend() does:

verifies interval has passed
ABI-encodes transfer(recipient, amount)
updates lastExecuted
requests Safe execution via execTransactionFromModule

Execution path:

any caller
  -> StipendModule.stipend()
      -> Safe.execTransactionFromModule(token, transferData, Call)
          -> ERC20.transfer(recipient, amount)

Why this is useful:

deterministic recurring transfer
no monthly signer fatigue
signer control still exists because owners can disable the module

Runbook

Deploy module with Safe, token, recipient, amount
Enable module in Safe with enableModule(moduleAddress)
Wait for interval
Call stipend()
Repeat calls every interval (manual or automated)
Disable module when policy changes

Security Notes Before Production

This sample is intentionally simple. Harden before mainnet:

Access policy: stipend() is permissionless by design in this sample
Observability: emit events to improve traceability
Emergency controls : consider pause or kill-switch patterns aligned with governance model
Token assumptions: test exact token behavior (non-standard ERC20 behavior exists)

Where to Go Next

If you understand this stipend module pattern, you already understand the core mechanism behind most Safe module and how it can lead to streamline operations of DAOs.

This is a very simple example of how to build a module, explore Zodiac or Gnosis Safe Module repositries for more:

References

Gnosis Safe Modules docs: https://docs.safe.global/advanced/smart-account-modules
How to add a module: https://help.safe.global/en/articles/40826-add-a-module
Safe modules examples: https://github.com/safe-fndn/safe-modules
Safe smart account contracts: https://github.com/safe-fndn/safe-smart-account

Building a Multi-Chain Safe Wallet Monitor

doncesarts — Tue, 12 Aug 2025 15:54:00 +0000

Solving Multi-Chain Safe Wallets Monitoring

When managing multiple Gnosis Safe wallets across different blockchain networks, teams often face notification fatigue - especially when using individual monitoring tools like Den that create separate alerts for each Safe-Transaction. Or have to manually remind signers of all the queued transactions that need to be signed.

Here's how I built a unified monitoring solution that aggregates pending transactions across multiple chains.

The Problem

Multi-sig wallets are crucial for DAOs and protocol treasuries, but monitoring dozens of Safes across Ethereum, Arbitrum, Optimism, and other chains creates overwhelming notification noise. Each Safe generates separate alerts, making it difficult to prioritize actions.

Technical Solution

Full implementation can be found at https://github.com/doncesarts/onchain-toolkit/tree/main/packages/safe-wallet-monitor .

Core Architecture

The solution leverages Safe's public APIs without requiring authentication, using a three-stage approach:

Parallel Data Fetching - Query multiple chains simultaneously
Smart Aggregation - Consolidate related transactions
Actionable Formatting - Present unified summaries

Key Implementation Details

Multi-Chain API Coordination:

const SAFE_API_URLS: Record<ChainName, string> = {
  mainnet: 'https://safe-transaction-mainnet.safe.global',
  arbitrum: 'https://safe-transaction-arbitrum.safe.global',
  optimism: 'https://safe-transaction-optimism.safe.global',
  // ... 8+ networks supported
};

Separation of Concerns

export async function monitorSafeWalletQueue(
  config: SafeWalletMonitorConfig
): Promise<SafeWalletMonitorResult> {
   ...
  // Fetch all transaction data
  const transactionData = await fetchAllQueuedTransactions(safes, formatOptions, debug);
   ...

  // Format the data for display
  const { messages, signerSummary } = formatTransactionData(
    transactionData,
    signers,
    formatOptions
  );

  // Create the final message
  const finalMessage = messages.join('\n');
   ...  
   await sendNotifications(notifications, finalMessage);

  return {
    totalTransactions,
    messages,
    signerSummary,
    rawData: transactionData,
  };
}

Efficient Data Pipeline:

export async function fetchAllQueuedTransactions(
  safes: SafeAddress[],
  options: FormatOptions,
  debug = false
): Promise<QueuedTransactionData[]> {

  // Group safes by chain to minimize API calls
  const safesByChain = safes.reduce(
    (acc, safe) => {
      if (!acc[safe.chain]) acc[safe.chain] = [];
      acc[safe.chain].push(safe.address);
      return acc;
    },
    {} as Record<ChainName, string[]>
  );

  const results: QueuedTransactionData[] = [];

  // Process each chain sequentially to avoid rate limiting
  for (const [chain, addresses] of Object.entries(safesByChain)) {
    const chainKey = chain as ChainName;

    for (const address of addresses) {
      try {
        // Fetch transactions and Safe info in parallel for efficiency
        const [transactions, safeInfo] = await Promise.all([
          fetchQueuedTransactions(address, chainKey, debug),
          options.showConfirmedSigner || options.showPendingSigner
            ? fetchSafeInfo(address, chainKey)
            : Promise.resolve(null),
        ]);

        // Skip if no transactions found
        if (transactions.length === 0) {
          if (debug) {
            console.log(`[Debug] No queued transactions for ${address} on ${chain}`);
          }
          continue;
        }

        // Fetch transaction notes if enabled
        if (options.showTxNote) {
          for (const tx of transactions) {
              const txDetails = await fetchTransactionDetails(tx.id, chainKey);
              if (txDetails?.note) {
                tx.note = txDetails.note;
              }
          }
        }

        const safeUrl = generateSafeUrl(address, chainKey);

        results.push({
          chain: chainKey,
          address,
          transactions,
          safeInfo,
          safeUrl,
        });


      } catch (error) {
        console.error(`Failed to fetch data for Safe ${address} on ${chain}:`, error);
      }
    }
  }

  return results;
}

Fetch information about a Safe, including owners and threshold:

export async function fetchSafeInfo(
  safeAddress: string,
  chain: ChainName
): Promise<SafeInfo | null> {
  try {
    const apiUrl = SAFE_API_URLS[chain];
    if (!apiUrl) {
      throw new SafeApiError(`Unsupported chain: ${chain}`, safeAddress);
    }

    const response = await axios.get(`${apiUrl}/api/v1/safes/${safeAddress}/`);

    return {
      owners: response.data.owners || [],
      threshold: response.data.threshold || 1,
    };
  } catch (error) {
    console.error(`Failed to fetch Safe info for ${safeAddress} on ${chain}:`, error);
    return null;
  }
}

Fetch all queued (pending) transactions for a Safe

export async function fetchQueuedTransactions(
  safeAddress: string,
  chain: ChainName,
  debug = false
): Promise<QueuedSafeTransaction[]> {
  const log = createLogger(debug);

  try {
    const url = `https://safe-client.safe.global/v1/chains/${chainIds[chain]}/safes/${safeAddress}/transactions/queued`;
    log(`Fetching queued transactions for ${safeAddress} on ${chain} \n  ${url}`);

    // Fetch queued transactions from the Safe API
    const response = await axios.get<SafeClientApiResponse>(url, {
      timeout: 20_000,
      headers: {
        Accept: 'application/json',
        'User-Agent': 'safe-wallet-monitor/1.0',
      },
    });

    // Filter only TRANSACTION type results and convert to enhanced format
    const transactions = response.data.results
      .filter(item => item.type === 'TRANSACTION')
      .map(item => convertToEnhancedFormat(item, safeAddress))
      .filter((tx): tx is QueuedSafeTransaction => tx !== null);
    log(`Found ${transactions.length} queued transactions`);
    return transactions;
  } catch (error) {
    console.error(`Failed to fetch queued transactions for ${safeAddress} on ${chain}:`, error);
    return [];
  }
}

Fetch detailed information about a specific transaction, including notes

export async function fetchTransactionDetails(
  transactionId: string,
  chain: ChainName
): Promise<{ note?: string } | null> {
  try {
    const chainId = chainIds[chain];
    const url = `https://safe-client.safe.global/v1/chains/${chainId}/transactions/${transactionId}`;

    if (!chainId) {
      throw new SafeApiError(`Unsupported chain: ${chain}`, transactionId);
    }

    const response = await axios.get<SafeTransactionDetails>(url);

    return {
      note: response.data.note || undefined,
    };
  } catch (error) {
    // Transaction details are optional, so we don't throw errors here
    console.warn(`Could not fetch transaction details for ${transactionId}:`, error);
    return null;
  }
}

Smart Rate Limiting:

Process chains sequentially to avoid API throttling
Implement reasonable polling intervals
Graceful error handling for network issues

Innovation: Signer-Centric Aggregation

Instead of Safe-centric notifications, the tool groups by who needs to act:

// Count missing signatures per signer across ALL safes
for (const tx of transactions) {
  if (tx.missingSigners) {
    for (const signerAddress of tx.missingSigners) {
      signerSummary[signerAddress] = (signerSummary[signerAddress] || 0) + 1;
    }
  }
}

This creates actionable summaries like:

@alice: 5 signatures needed
@bob: 2 signatures needed

Technical Advantages

Zero Dependencies on External npm packages:

Uses only public Safe APIs
No API keys or registration required
Perfect for serverless deployments (AWS Lambda, Vercel)

Memory-Efficient Processing:

Streams transaction data without storing full blockchain state
Minimal memory footprint suitable for edge computing

Extensible Design:

Modular notification system (Telegram, webhooks, console)
Configurable formatting options
Easy to add new chains or notification channels

Real-World Impact

For teams managing 10+ Safes across multiple chains:

90% reduction in notification noise
Consolidated view of all pending actions
Clear prioritization of urgent transactions

The tool processes hundreds of pending transactions in seconds while maintaining sub-100KB memory usage, making it ideal for cost-effective serverless monitoring.

CLI Usage Example

The tool is designed for easy deployment and automation. Here's how to use it:

Installation via npm:

npm install -g @onchain-toolkit/safe-wallet-monitor

Installation from source:

git clone git@github.com:doncesarts/onchain-toolkit.git
cd onchain-toolkit/packages/safe-wallet-monitor
npm install
npm run build
npm link

Configuration file (safe-monitor.config.json):

{
  "safes": [
    {
      "address": "0x5feA4413E3Cc5Cf3A29a49dB41ac0c24850417a0",
      "chain": "mainnet"
    },
    {
      "address": "0xD86CEB76e9430D3bDE90ded79c82Ae62bc66d68b",
      "chain": "arbitrum"
    }
  ],
  "signers": [
    {
      "address": "0x2BE293361aEA6136a42036Ef68FF248fC379b4f8",
      "handle": "alice"
    },
    {
      "address": "0x327Db4C2e4918920533a05f0f6aa9eDfB717bB41",
      "handle": "bob"
    }
  ],
  "formatOptions": {
    "showPendingSigner": true,
    "showStatusIcon": true,
    "showChainIcon": true
  },
  "notifications": [
    {
      "type": "telegram",
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "chatId": "YOUR_CHAT_ID"
    }
  ]
}

Run the monitor:

safe-wallet-monitor --config safe-monitor.config.json

Sample Output

The tool provides rich, actionable output across multiple channels:

Console Output:

🔍 Tracking 3 Safe(s) across 2 chain(s)...

⚫ MAINNET - Tx 42 🏅 3/3
    📝 Note: Treasury allocation for Q4 rewards
    ⏳ Not Signed: Alice, Bob
🔗 Safe URL: https://app.safe.global/home?safe=eth:0xbe2AB3d3d8F6a32b96414ebbd865dBD276d3d899

🔵 ARBITRUM - Tx 15 ⚠️ 1/3
    📝 Note: Bridge funds to Optimism
    ⏳ Not Signed: Alice, Bob, Charlie
🔗 Safe URL: https://app.safe.global/home?safe=arbitrum:0x6626593C237f530D15aE9980A95ef938Ac15c35c

📊 Action Required:
   • @Alice: 2 signature(s) needed
   • @Bob: 2 signature(s) needed
   • @Charlie: 1 signature(s) needed

Telegram Notifications

The tool sends rich HTML-formatted messages to Telegram for real-time alerts:

Setup Telegram Bot:

Message @BotFather on Telegram
Create a bot and get your token
Get your chat ID by adding the bot to a chat and visiting: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

Telegram Configuration:

{
  "notifications": [
    {
      "type": "telegram",
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN_HERE",
      "chatId": "YOUR_CHAT_ID_HERE",
      "disableNotification": false,
      "parseMode": "HTML"
    }
  ]
}

Telegram Message Example:

🔍 Governance Alert

⚫ MAINNET - Tx 42 🏅 3/3
📝 Treasury allocation for Q4 rewards
⏳ Pending: Alice, Bob

🔵 ARBITRUM - Tx 15 ⚠️ 1/3  
📝 Bridge funds to Optimism
⏳ Pending: Alice, Bob, Charlie

📊 Summary: 2 transactions need attention

Perfect for cron jobs or serverless functions that need to check transaction status periodically.

Full Implementation: The complete source code and documentation can be found at https://github.com/doncesarts/onchain-toolkit/tree/main/packages/safe-wallet-monitor

Open Source & MIT Licensed - Available as part of the @onchain-toolkit ecosystem.