31Third Safe Rebalancer#

This skill helps you monitor portfolio drift and prepare/execute policy-compliant rebalances on a Gnosis Safe through the 31Third ExecutorModule.

Best-practice usage:

• Use one-step execution by default: npm run cli -- rebalance-now.
• Only use separated tools ( check_drift, plan_rebalance, execute_rebalance, etc.) if you explicitly understand each step and want manual control.
• If unsure, run help first ( npm run cli -- help) and follow that guidance.

Prerequisites#

• Node.js 22+
• npm

Local Setup#

bash

npm install
npm run build

Getting Started#

If you have not deployed your policy stack yet, deploy it first: https://app.31third.com/safe-policy-deployer

Set required environment variables:

bash

SAFE_ADDRESS=0xYourSafe
CHAIN_ID=8453
TOT_API_KEY=your_api_key
RPC_URL=https://mainnet.base.org
EXECUTOR_MODULE_ADDRESS=0xYourExecutorModule
EXECUTOR_WALLET_PRIVATE_KEY=0x...
ORACLE_MAX_AGE_SECONDS=3600
HEARTBEAT_INTERVAL_SECONDS=21600

TOT_API_KEY (31Third API key) can be requested via https://31third.com/contact or by emailing dev@31third.com.

Wallet model and key handling:

• Safe owner wallet: controls Safe ownership/governance operations. Never share this private key with the skill.
• Executor wallet: configured as executor on ExecutorModule in the wizard. This private key is required by the skill for execute_rebalance.
• The final step of the 31Third wizard provides an overview of all required environment variables. Use that as source of truth when configuring this skill.

What This Skill Does#

• Reads active on-chain policies from ExecutorModule.
• Computes current-vs-target drift ( check_drift).
• Validates trades against Asset Universe + Slippage boundaries ( validate_trade).
• Runs a configurable heartbeat monitor ( automation) and returns an alert payload when drift exceeds threshold.
• Simulates and executes approved rebalance batches ( execute_rebalance) with pre-execution checkPoliciesVerbose validation and one retry on unknown execution failures.
• Accepts SDK plan_rebalance output directly for execution ( txData + requiredAllowances) and decodes batch trade calldata internally.
• Fast-fails execution if scheduler != registry on the ExecutorModule, printing both addresses.
• Generates SDK-based policy-aware trade plans ( plan_rebalance) using current Safe balances (bounded by Asset Universe when present) as baseEntries.
• Provides one-command execution ( rebalance_now) for non-technical users: drift check -> SDK plan -> execution.
• Returns setup and capability guidance ( help).

Execution Safety#

Before execution, the agent provides a clear reason, for example:

• BTC is at 54.00%, target is 50.00% (drift 400 bps). Rebalance required.

The skill uses:

• Viem publicClient for all reads.
• Viem walletClient for execution.

Execution Contract (Important)#

When using SDK/trading-api rebalancing output, execution must follow this exact pattern:

1. Build approvals from requiredAllowances as (tokenAddress, neededAllowance).

2. Decode txData as batchTrade(trades, config).

3. Re-encode encodedTradeData as ABI tuple:

   • tuple(string,address,uint256,address,uint256,bytes,bytes)[]
   • tuple(bool,bool)

4. Run checkPoliciesVerbose(tradesInput, configInput) before submitting.

5. Read scheduler and registry from ExecutorModule.

6. Ensure the signing executor wallet address equals registry (required by onlyRegistry).

7. Only execute immediate path ( executeTradeNow(approvals, encodedTradeData)) when scheduler == registry.

8. If scheduler != registry, fail fast and show both addresses.

This is the required execution semantics for this skill and should not be changed to raw passthrough calldata execution.

CLI#

Run the bundled CLI:

bash

npm run cli -- help
npm run cli -- check-drift
npm run cli -- automation --last-heartbeat-ms 0
npm run cli -- plan-rebalance --signer 0xYourSigner --min-trade-value 100
npm run cli -- rebalance-now
npm run cli -- validate-trade --trade '{"from":"0x...","to":"0x...","fromAmount":"1000000000000000000","minToReceiveBeforeFees":"990000000000000000"}'
npm run cli -- execute-rebalance --trades '[{"exchangeName":"0x","from":"0x...","fromAmount":"1000000000000000000","to":"0x...","minToReceiveBeforeFees":"990000000000000000","data":"0x...","signature":"0x..."}]' --approvals '[{"token":"0x...","amount":"1000000000000000000"}]'
npm run cli -- execute-rebalance --rebalancing '{"txData":"0x...","requiredAllowances":[{"token":{"address":"0x..."},"neededAllowance":"1000000000000000000"}]}'

Read-only smoke preflight:

bash

npm run smoke -- --signer 0xYourSigner
npm run smoke -- --trades '[...]' --approvals '[...]'

Notes#

• This skill is automation infrastructure, not investment advice.
• Validate behavior in test/staging before running in production.