31Third Safe Rebalancer
by @phips0812
Policy-aware Safe portfolio rebalancing assistant for 31Third ExecutorModule.
clawhub install 31third-safe-rebalancerπ About This Skill
name: 31third-safe-rebalancer description: Policy-aware Safe portfolio rebalancing assistant for 31Third ExecutorModule. homepage: https://31third.com
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:
npm run cli -- rebalance-now.check_drift, plan_rebalance, execute_rebalance, etc.) if you explicitly understand each step and want manual control.help first (npm run cli -- help) and follow that guidance.Prerequisites
Local Setup
npm install
npm run build
Getting Started
If you have not deployed your policy stack yet, deploy it first:
Set required environment variables:
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 dev@31third.com.
Wallet model and key handling:
ExecutorModule in the wizard. This private key is required by the skill for execute_rebalance.What This Skill Does
ExecutorModule.check_drift).validate_trade).automation) and returns an alert payload when drift exceeds threshold.execute_rebalance) with pre-execution checkPoliciesVerbose validation and one retry on unknown execution failures.plan_rebalance output directly for execution (txData + requiredAllowances) and decodes batch trade calldata internally.scheduler != registry on the ExecutorModule, printing both addresses.plan_rebalance) using current Safe balances (bounded by Asset Universe when present) as baseEntries.rebalance_now) for non-technical users: drift check -> SDK plan -> execution.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:
publicClient for all reads.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:
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:
npm run smoke -- --signer 0xYourSigner
npm run smoke -- --trades '[...]' --approvals '[...]'
Notes
π‘ Examples
If you have not deployed your policy stack yet, deploy it first:
Set required environment variables:
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 dev@31third.com.
Wallet model and key handling:
ExecutorModule in the wizard. This private key is required by the skill for execute_rebalance.