31third-safe-rebalancer

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:

• 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

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:

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 [e-mail].

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:

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

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