OpenAllocator

A harness for AI agents to run policy-bounded DeFi yield allocation on the 1Tx API — every step a JSON-out CLI command an agent can drive.

Install · Talking to Your Agent · Commands · Safety · Disclaimer

_{A plain-language ask → a policy-clean $10k book, the honest "this passed set is a Morpho-on-Base monoculture" finding, and a proposal artifact that signs nothing without your go-ahead. · ▶ Watch a full run}

open-allocator is an open-source, agent-operated DeFi yield allocator built on the 1Tx API and run as a CLI. It discovers the live 1Tx instrument universe, scores yield venues transparently, builds policy-bounded allocations, and executes through a self-custody wallet — only after explicit confirmation.

This is portfolio construction, not yield-chasing. Most "auto-yield" tools sweep funds into whatever APY is highest this hour. open-allocator does what a professional asset allocator does — it builds a diversified allocation across explicit risk/reward metrics (Sharpe, volatility, drawdown), risk tiers, and real portfolio structures (core_satellite, risk_parity/inverse_vol, sleeves, ladder), bounded by an explicit policy — and runs it through an agent instead of a desk. High APY is a risk input, never the objective.

This is an end-user allocator, not Morpho's curator-side Allocator role.

APY is descriptive, not predictive. Rates move, rewards end, liquidity changes, and smart-contract risk remains. Every metric here is yield-path only — never principal, depeg, bridge, or contract-loss risk.

---

Why It Exists

• Professional allocation, not APY-chasing — risk/reward metrics, risk tiers, and portfolio strategies (core_satellite, risk_parity, sleeves, ladder) — the way an allocator builds a book, not a sweep to the top rate.
• Dynamic discovery — no hardcoded protocol or chain universe; new networks and instruments are picked up automatically from 1Tx.
• Transparent scoring — every allocation and risk score maps to visible inputs. Unknown fields stay Unknown instead of being guessed.
• Policy-bounded execution — allowlists and caps block unsafe proposals before signing. Policy can only tighten, never loosen.
• CLI-first — agents and humans use the same JSON-out commands. Every command prints one JSON object to stdout.
• Self-custody, and gasless — the wallet signs and broadcasts its own transactions. With a Safe smart account it pays gas in USDC instead of native tokens, so you fund one chain and never top up ETH anywhere.

How It Works

The system has two planes:

• Research / decision plane (agentic). Agents and humans discover the universe, compare scored instruments, screen by risk, backtest, and propose weights — freely and read-only.
• Execution plane (deterministic). Python in open_allocator.core and open_allocator.exec validates schemas, enforces policy, builds transaction plans, and blocks unsafe execution. The executor never runs agent-authored code.

A decision leaves the research plane only as a validated artifact — explicit weights or a named+parameterized strategy — and must pass check-policy before any transaction is built.

flowchart TB
    subgraph RP["Research / decision plane — agentic, read-only"]
      direction LR
      D["discover<br/>list-vaults"] --> SC["score"] --> SN["screen"] --> BT["backtest"] --> PR["propose weights<br/>build-allocation"]
    end
    PR -->|"validated artifact<br/>(explicit weights or named strategy)"| G{"check-policy<br/>block-only gate"}
    G -->|violation| X["abort<br/>no transaction built"]
    G -->|pass| EP
    subgraph EP["Execution plane — deterministic, policy-bounded"]
      direction LR
      VS["validate schemas"] --> EF["enforce policy"] --> BP["build tx plan"] --> SB["sign + broadcast<br/>confirmation-gated"]
    end

Loading

Install

Requires Python >=3.12,<3.13 and uv.

uv sync
uv run open-allocator --help

Configure

Create a 1Tx account and generate an API key at app.1tx.fi/settings, then copy .env.example to .env and set:

Variable	Purpose
ONE_TX_API_URL, ONE_TX_API_KEY	1Tx API endpoint and key — create the key at app.1tx.fi/settings.
SIGNER_ACCOUNT	eoa (default) or safe — what holds the funds.
SIGNER_SUBMISSION	rpc (default) or erc4337-paymaster — how the tx reaches the chain.
SIGNER_OWNER	local (default) or remote — where the signing key lives.
ONE_TX_PRIVATE_KEY	Funded EOA key; required only for a local-key EOA over RPC.
RPC_URL_<chainId>	Override the built-in public RPC for a chain (required for broadcast).
ONE_TX_SLIPPAGE_BPS, ONE_TX_FAST_TRANSFER	1Tx transaction options.

Governance lives in policy.yaml — the allocator's constitution. It defines allowed axes (protocols, chains, asset_categories, stablecoin_only, assets, curators), caps (per-instrument / protocol / curator / chain weight, min TVL, max LLTV, max reward dependence), and gates (new-instrument approval, autonomous rebalance, max deploy per cycle). Allowlists are narrowing filters over discovery (null = all); they never replace discovery.

Talking to Your Agent

open-allocator is a harness: you don't type CLI commands, your agent does. Point a coding agent (Claude Code, Cursor, or any agent that can run a shell) at this repo — it reads AGENT_GUIDE.md and the skills — and then you drive everything in plain language. The agent translates your intent into the JSON-out commands below, and every spend stays confirmation-gated.

Discover & analyze (read-only)

"Show me the highest-scoring stablecoin venues 1Tx can see right now, and explain why the top three rank where they do."

"Screen for anything with Sharpe above 1 and max drawdown under 10%, stablecoin-only, then build me a balanced $10k allocation."

"Backtest that allocation against just holding USDC and show me the drawdown."

Check policy & execute (confirmation-gated)

"Check this allocation against my policy — tell me exactly what would block before I sign anything."

"Looks good — execute it, but first walk me through the wallet, chains, instruments, amounts, and gas."

"Rebalance my current positions toward this target and show me the diff before broadcasting anything."

"Withdraw position X and tell me what I'll receive, in shares."

The agent never signs or broadcasts without announcing the exact action and getting your confirmation (see Safety). The Commands below are what it runs under the hood — you can also run them directly.

Commands

Every command emits one JSON object on stdout; errors emit one JSON object on stderr and exit non-zero.

Discovery & read-only

uv run open-allocator wallet-status                 # address, USDC + native-gas readiness per chain
uv run open-allocator safe-address                  # the derived Safe: same address on every chain
uv run open-allocator list-vaults --sort score      # discover + score the live universe
uv run open-allocator score-vault --instrument-id <id>
uv run open-allocator positions                     # reconcile current on-chain holdings

Analysis & planning (read-only)

uv run open-allocator screen --min-sharpe 1.0 --max-drawdown 0.1   # advisory risk narrowing
uv run open-allocator build-allocation --amount 10000 --risk balanced
uv run open-allocator simulate  --allocation allocation.json       # forward blended-APY / concentration
uv run open-allocator backtest  --allocation allocation.json       # daily-compounded NAV vs benchmark
uv run open-allocator check-policy --allocation allocation.json    # block-only policy gate

build-allocation supports risk presets, allocation strategies (--strategy), advisory screening flags, --exclude, pinned weights (--pin id=weight), and a full allocation-spec via --spec. Available strategies: score_weighted (default), equal_weight, risk_parity/inverse_vol, core_satellite, and sleeves/ladder.

Execution (confirmation-gated)

uv run open-allocator build-tx  --allocation allocation.json       # calldata plan (dry run)
uv run open-allocator execute   --allocation allocation.json --confirm
uv run open-allocator rebalance --current positions.json --target allocation.json --confirm
uv run open-allocator withdraw  --position <id> --confirm

Without --confirm, execution commands return a plan / dry-run report and broadcast nothing. execute --confirm is the spend path. Exits are share-denominated (ERC-4626 shares, not USDC guesses).

Gas in USDC (no native tokens)

Set SIGNER_ACCOUNT=safe and SIGNER_SUBMISSION=erc4337-paymaster and the allocator runs from a Safe smart account that pays its own gas in USDC:

flowchart LR
    F["Fund ONE chain<br/>USDC only, no ETH"] --> SA["Counterfactual Safe<br/>same address on every chain<br/>deploys itself on first op"]
    SA -->|same-chain buy| DEP["Deposit<br/>one atomic op<br/>gas paid in USDC"]
    SA -->|cross-chain buy| BR["Bridge over CCTP<br/>1Tx settles the destination mint"]
    DEP -->|exit| EX["Batched exit<br/>redeems USDC, pays its own gas<br/>on a chain that held nothing"]
    BR --> POS["positions<br/>reports what actually landed"]

Loading

• The Safe is counterfactual — derived from your owner list, the same address on every chain, and it deploys itself inside its first operation on each chain. Nothing to create up front.
• A chain's plan steps go out as one atomic operation. Because the paymaster charges after execution, an exit pays its gas out of the USDC it just redeemed — on a chain where the Safe held nothing at all.
• Cross-chain deposits bridge over CCTP without deploying anything on the destination.

Net effect: fund one chain. Deposits bridge out, exits pay their own way back, and no chain ever needs native gas.

A cross-chain buy has two legs with one owner each. The allocator signs, submits, and reports the source-chain leg — execute returns once that transaction lands. Relaying the CCTP message and minting on the far side is 1Tx's to settle; the allocator does not poll the bridge by design. Read what actually landed with positions. An operation that has settled nothing — a bundler hasn't included the user-op, a Safe is awaiting signatures — reports in_progress, never success.

This path has been exercised end to end on Base and Arbitrum mainnet. The model, the traps, and its known limits are in docs/gasless-execution.md.

Agent Operation

Agents start with AGENT_GUIDE.md, the operating contract for this repository. Shared architecture and invariants are in PROJECT_CONTEXT.md.

Stage skills and workflow graphs describe how to drive the CLI and review artifacts:

• Skills: discover, score, build-allocation, agentic-allocation, execute-with-1tx, rebalance, withdraw, plus risk-review and checkpoint-protocol.
• Workflows: allocate, rebalance, withdraw.
• Artifact schemas: schemas/.

Safety

• Never sign, broadcast, rebalance, or withdraw without first announcing the exact action (wallet, chains, instruments, amounts, gas assets, policy result, failure modes) and obtaining confirmation.
• Policy violations abort before any transaction is built or signed. --unsafe / --autonomous are not shortcuts — use them only when policy and task explicitly require it.
• Keep private keys out of logs and artifacts.
• Treat high APY as a risk input, not a promise.

Development

uv run ruff check
uv run pytest            # 542 passed, 3 integration tests skipped without live creds

Unit tests mock 1Tx over httpx.MockTransport and the chain over eth-tester; no live network is touched. Live API/RPC tests are opt-in behind @pytest.mark.integration and explicit credential gates.

Layout: src/open_allocator/core (allocation, scoring, policy, risk metrics, strategies, screening, backtest, positions, checkpoints), src/open_allocator/exec (1Tx client, signers, executor, RPC registry), schemas/ (JSON artifact contracts), skills/ + workflows/ (agent instruction layer), docs/ (reference notes).

The live 1Tx risk-factor field refresh remains credential-gated; see docs/onetx-analysis-fields.md.

---

Disclaimer

This software is provided "as is", without warranty of any kind, express or implied (see LICENSE). It is alpha, unaudited software that signs and broadcasts real on-chain transactions and moves real funds.

• Not financial, investment, legal, or tax advice. Nothing produced by this tool — scores, backtests, allocations, or projections — is a recommendation to buy, sell, or hold any asset. You are solely responsible for your own decisions.
• APY is descriptive, not predictive. Rates move, rewards end, liquidity changes, and smart-contract, depeg, bridge, and principal-loss risks remain. Metrics here are yield-path only.
• Use at your own risk. DeFi carries risk of total loss. Only use funds you can afford to lose, run your own review, and always inspect a proposed transaction before confirming it.
• The authors and contributors accept no liability for any loss or damage arising from use of this software.