Generating payouts

How to run the payout script to generate solver transfer files or post transactions to Safe.

The payout script (src.fetch.transfer_file) is the main entry point for computing solver reimbursements and COW token rewards for a given accounting period. It queries the CoW Protocol orderbook database and Dune Analytics, computes per-solver amounts, then either writes CSV files or posts a multisend transaction directly to the Safe.

Accounting periods

Accounting periods are fixed 7-day intervals, defined as:

StartTime <= block_time < EndTime

Payouts run every Tuesday, covering the prior 7 days. When you run the script without --start, it defaults to today - 7 days as the period start. If the script cannot be run on Tuesday, pass --start explicitly to anchor the correct period.

Do not run the script immediately after a period ends. Some data sources (price feeds, ethereum.transactions, event data) require additional time to finalize. Wait a reasonable interval before executing.

CLI flags

The script accepts the following arguments:

Flag	Type	Default	Description
--start YYYY-MM-DD	str	today - 7 days	Accounting period start date
--post-tx	flag	false	Encode and post the multisend transaction to Safe
--dry-run	flag	false	Encode but do not post; sends Slack notification instead
--send-to-slack	flag	false	Send results summary to Slack without posting a transaction

The --post-tx flag requires PROPOSER_PK to be set in your environment. The --dry-run and --send-to-slack flags both require SLACK_TOKEN and SLACK_CHANNEL.

Modes of operation

Manual (default)

Generates two CSV files in the out/ directory. You then import these into the Safe app to build the transaction manually.

Auto-propose

Pass --post-tx to encode the full multisend and post it to the Safe transaction queue automatically.

Dry-run

Pass --post-tx --dry-run to encode the transaction without posting it. Sends a Slack message with the summary for review.

Output files

In manual mode, the script writes two CSV files to the out/ directory (configured by FILE_OUT_PATH in .env):

out/transfers-{network}-{period}-COW.csv
out/transfers-{network}-{period}-NATIVE.csv

For example, for mainnet over the period March 14–21, 2023:

out/transfers-mainnet-2023-03-14-to-2023-03-21-COW.csv
out/transfers-mainnet-2023-03-14-to-2023-03-21-NATIVE.csv

These CSVs conform to the Safe airdrop format, with amounts as floats and token_address set to null for native token transfers.

Minimum transfer thresholds

Transfers below these thresholds are filtered out before writing or posting. Values are per-network:

Network	Min native transfer	Min COW transfer
Mainnet	0.001 ETH	10 COW
Gnosis	0.01 xDAI	1 COW
Arbitrum One	0.0001 ETH	1 COW
Base	0.0001 ETH	1 COW
Avalanche	0.0001 AVAX	1 COW
Polygon	0.0001 POL	1 COW
BNB	0.0001 BNB	1 COW
Linea	0.0001 ETH	1 COW
Plasma	0.0001 XPL	1 COW
Ink	0.0001 ETH	1 COW

Dashboard URL

At startup, the script prints a Dune Analytics dashboard URL to the console. The URL encodes the accounting period, blockchain, quote reward, and quote cap so the dashboard is pre-filtered to the exact period being processed:

https://dune.com/cowprotocol/cow-solver-rewards?start_time=...&end_time=...&blockchain=...&quote_reward=...&quote_cap_native_token=...

Use this URL to cross-check the computed transfers against the on-chain data before proceeding.

Command examples

Quickstart — generate CSV files for the last 7 days

python -m src.fetch.transfer_file

Specify an explicit start date

python -m src.fetch.transfer_file --start 2023-03-14

This runs for the accounting period March 14–21, 2023.

Auto-propose: post multisend directly to Safe

python -m src.fetch.transfer_file --start 2023-03-14 --post-tx

Requires PROPOSER_PK in your environment. Encodes COW transfers (mainnet), native transfers (network), and an overdrafts update as three separate Safe transactions.

Dry-run: encode but do not post, notify Slack

python -m src.fetch.transfer_file --start 2023-03-14 --post-tx --dry-run

Enodes the full multisend but does not submit it. Sends a Slack notification with the summary.

Send results to Slack without posting a transaction

python -m src.fetch.transfer_file --send-to-slack

Runs in manual mode but additionally posts the summary to the configured Slack channel.

View all options

python -m src.fetch.transfer_file --help

Late runs

If Tuesday passes without the script running, specify --start explicitly to set the correct period start:

# Running on Wednesday for the period that should have started Tuesday
python -m src.fetch.transfer_file --start 2023-03-14

The end date is always computed as start + 7 days, so the period boundary is always exact regardless of when you run the script.