Lucho Treasury

Keep tomorrow's money liquid. Give the true surplus a job.

Lucho Treasury is a goal-aware treasury agent built for Track A of the Binance Agent OS Mini Hackathon. A user explains what their stablecoins must pay for and when. Lucho protects those obligations first, evaluates only the remaining surplus, stress-tests every proposed allocation, and returns an explainable ALLOCATE, HOLD, or BLOCK decision.

It is deliberately not a highest-APY bot. The highest rate is a bad recommendation if payroll is due before the money can be redeemed.

One-line pitch: Lucho combines live Binance Agent OS context with deterministic treasury guardrails so an AI agent can put idle money to work without gambling with money that already has a job.

Contents

• The mental model

• The problem

• What Lucho does

• Why this is different

• Track A fit

• The complete flow, step by step

• A worked example

• Architecture: two MCP servers, one agent

• Why Binance Agent OS is indispensable

• MCP: use Lucho from Codex, Claude, or another agent

• Run and verify locally

• Safety model

• What is real today

• Submission status

The mental model

Think of Lucho as a cautious treasury operator sitting between an AI assistant and financial tools:

Binance tells the agent what is true now.
The user tells the agent what the money must do later.
Lucho calculates what is genuinely free to use.
Policy—not the language model—sets the maximum allocation.

The language model can explain a plan, ask for clarification, reduce it, or veto it. It cannot increase the policy engine's maximum, hide a failed stress test, or turn on execution.

The problem

Treasury balances often look idle while already carrying future obligations: payroll, rent, contractors, tax, cloud costs, or an autonomous agent's API budget. A naive yield agent sees 1,000 USDT and asks, “Which product pays the most?” Lucho asks three safer questions first:

1. How much must remain liquid?

2. When must that capital be available again?

3. What is the worst acceptable result if access or rates deteriorate?

Only after answering those questions does Lucho compare earning options.

What Lucho does

Lucho turns a natural-language treasury goal into a constrained, auditable plan:

• protects a permanent liquid reserve;

• protects liabilities that fall inside the planning horizon;

• caps the total allocation and exposure to any one product;

• rejects unavailable, mismatched, over-duration, over-risk, or below-floor products;

• ranks eligible products by risk-adjusted rather than headline APR;

• tests early-liability, temporary-liquidity, and rate-drop scenarios;

• lets an AI review layer tighten—but never enlarge—the deterministic plan;

• fingerprints the policy and creates a redacted decision receipt;

• keeps all financial writes disabled in the submitted prototype.

Why this is different

The result is not merely a chatbot around an exchange API. It is a reusable control layer that makes an agent explain and respect the job the money already has.

Track A fit

The project targets Track A: build an AI agent using Agent OS. The official Binance Agentic MCP provides live exchange context; the Lucho MCP contributes the new goal-aware decision workflow. The recording can visibly show one host using both servers in the same task.

The published Track A entry instructions ask for a video or demo plus GitHub when applicable. They do not state that a smart contract, BNB Smart Chain deployment, or live trade is required. Lucho therefore spends the seven-day scope on a complete Agent OS workflow instead of adding an unrelated token or contract.

The complete flow, step by step

This is the complete user-to-receipt journey. The separation between the agent host, Binance, and Lucho is intentional and is the central safety design.

flowchart TD
    A[1. User states goal and liabilities] --> B[2. Agent reads authorized Binance context]
    B --> C[3. Agent normalizes balance and product terms]
    C --> D[4. Lucho validates every required field]
    D --> E[5. Protect reserve plus near-term liabilities]
    E --> F[6. Calculate true surplus and hard caps]
    F --> G[7. Reject and score products]
    G --> H[8. Build a bounded candidate allocation]
    H --> I[9. Run mandatory stress scenarios]
    I --> J{10. Safe and eligible?}
    J -- No --> K[HOLD or BLOCK with reasons]
    J -- Yes --> L[ALLOCATE proposal]
    L --> M[11. AI may tighten or veto only]
    M --> N[12. Redacted fingerprinted receipt]
    N -. future write path .-> O[Fresh action-specific human confirmation]

1. The user states the job of the money

The user gives the asset, future liabilities, dates, minimum reserve, capital-return deadline, allocation caps, minimum acceptable stressed rate, and risk appetite. Missing amounts or terms are not guessed.

Example:

I have 1,000 USDT. Keep 800 for payroll due in five days and always keep another 100 liquid.
Any allocated capital must be accessible within seven days. Use a low-risk policy.

2. The agent reads Binance context

The AI host—Codex, Claude, or another MCP client—uses the official Binance Agentic MCP for the minimum authorized live context it needs, such as a balance or market observation. OAuth remains between the user, the host, and Binance; Lucho never receives Binance credentials.

3. The host normalizes candidate product facts

Every candidate is converted into the small data contract Lucho understands: asset, kind, APR, duration, redemption delay, availability, minimum, maximum/quota, and whether its rate can vary. The agent must not invent missing terms. In the reproducible demo these values come from visibly labeled fictional fixtures.

4. Lucho validates the inputs

The MCP tool rejects malformed goals, mismatched assets, invalid numbers, and incomplete product records. Invalid products are retained as rejected evidence where possible instead of silently disappearing from the plan.

5. Lucho protects liquidity before looking at yield

The engine calculates:

protected_liquidity = minimum_liquid_reserve + liabilities_due_inside_horizon
raw_surplus         = max(0, available_balance - protected_liquidity)
policy_cap          = available_balance × maximum_allocation_percentage
true_surplus        = min(raw_surplus, policy_cap)

If protected needs exceed the balance, the decision is immediately BLOCK. Yield ranking never runs around a liquidity deficit.

6. Lucho applies hard allocation caps

The candidate amount can never exceed the true surplus, portfolio-wide cap, per-product concentration cap, or reported product quota. These are enforced in TypeScript after inputs are validated; they are not instructions the language model can reinterpret.

7. Lucho rejects and scores products

Each product receives explicit liquidity, duration, variability, and product-risk components. Lucho rejects products when capital would return too late, the risk score exceeds the user's policy, the stressed APR falls below the configured floor, the asset differs, or the product is unavailable. Eligible products are sorted by risk-adjusted APR.

8. Lucho creates a bounded proposal

The engine allocates only across eligible products, respecting every cap. It returns all accepted and rejected candidates so the user can see not only what won, but why alternatives lost.

9. Lucho stress-tests the proposal

Three scenarios are mandatory in the current engine:

1. a protected liability arrives one day early;

2. 25% of allocated flexible liquidity becomes temporarily unavailable;

3. variable rates fall by 50% and fixed rates by 20%.

A failed mandatory scenario produces BLOCK, not a warning hidden beneath a recommendation.

10. Lucho returns one clear decision

• ALLOCATE — a bounded amount passed eligibility and stress checks;

• HOLD — there may be surplus, but no candidate satisfies the policy;

• BLOCK — protected needs exceed funds or the proposed allocation fails a mandatory check.

Every decision includes protected liquidity, true surplus, product reasons, stress results, and a policy fingerprint.

11. The AI can only make the result safer

The review tool may lower the total, lower an individual amount, veto a product, or hold everything. Any attempt to increase an allocation is clamped to the deterministic maximum. This keeps useful model judgment without letting probabilistic reasoning override treasury policy.

12. Lucho produces proof, not a hidden action

The receipt records the mode, goal, source metadata, candidates, rejection reasons, allocations, stress outcome, confirmation status, execution status, and cryptographic fingerprints. It allowlists safe source fields and excludes credentials. In this submission, execution always says not-executed.

The engine also implements an expiring confirmation challenge bound to the exact allocation. That is a safety primitive for a future write adapter; no write adapter is included or enabled today.

A worked example

The default fixture makes the policy easy to inspect:

The arithmetic is deliberately simple:

protected liquidity = 800 payroll + 100 reserve = 900 USDT
raw surplus         = 1,000 balance - 900 protected = 100 USDT
policy cap          = 1,000 × 80% = 800 USDT
true surplus        = min(100, 800) = 100 USDT
maximum plan        = 100 USDT—not 1,000 USDT

The fictional 30-day locked candidate advertises the highest fixture APR, but Lucho rejects it because the user needs capital back inside seven days. An eligible candidate receives at most 100 USDT; the remaining 900 USDT stays liquid. If payroll is raised to 1,100 USDT, protected needs exceed the balance and Lucho returns BLOCK with zero allocation.

Architecture: two MCP servers, one agent

Lucho does not impersonate Binance and it does not embed exchange credentials. The agent host composes two independent MCP servers:

                         ┌──────────────────────────────┐
                         │ Agent host                   │
User goal ──────────────►│ Codex / Claude / MCP client  │
                         └──────────┬───────────┬───────┘
                                    │           │
                         live facts │           │ bounded reasoning
                                    ▼           ▼
                      ┌──────────────────┐  ┌─────────────────────┐
                      │ Binance Agent OS │  │ Lucho Treasury MCP  │
                      │ official remote │  │ local stdio server  │
                      │ MCP + OAuth      │  │ no credentials      │
                      └────────┬─────────┘  └──────────┬──────────┘
                               │                       │
                               ▼                       ▼
                      balance / market       plan / stress / receipt

This split gives each component one job:

Why Binance Agent OS is indispensable

Without Binance Agent OS, Lucho is a deterministic policy library operating on fixtures. Agent OS turns it into an agent workflow connected to current, authorized exchange context. It provides the official remote MCP surface and OAuth boundary through which a compatible host can obtain live facts without copying Binance secrets into this repository.

The integration has been verified: on September 8, 2026, the authenticated official Binance MCP returned BNBUSDT = 751.75000000 through spot.tickerPrice. The raw captured response is in evidence/binance-live-read.json. It is public market data only; no account data or write action was used. The Binance response contained no exchange timestamp, so the evidence separately records the local MCP capture time.

The demo deliberately pairs that real Agent OS read with fictional Earn fixtures. This proves the live integration while keeping the allocation reproducible and avoiding false claims about current product rates or executed subscriptions.

MCP: use Lucho from Codex, Claude, or another agent

Yes—this repository contains a real MCP server, not a prompt that only works in one assistant. It uses the official TypeScript MCP SDK, exposes a standard local stdio transport, and is compiled to plain JavaScript. Any MCP host that can launch a local stdio server can discover and call it.

Tools exposed

The server also exposes the put-idle-money-to-work MCP prompt. It tells the host how to compose read-only Binance context with Lucho without inventing product facts or executing an action.

Prerequisites and build

• Node.js 20 or newer

• npm

• an MCP-compatible host such as Codex, Claude Code, Claude Desktop, Cursor, or an MCP client SDK

git clone YOUR_REPOSITORY_URL
cd lucho-treasury
npm install
npm run build

The portable server entry point is now:

/ABSOLUTE/PATH/TO/lucho-treasury/dist/mcp-server.js

Run it directly only when debugging; an MCP host normally starts and stops it automatically:

npm run mcp

An idle process is expected because stdio MCP waits for protocol messages on standard input.

Codex

codex mcp add lucho-treasury -- node /ABSOLUTE/PATH/TO/lucho-treasury/dist/mcp-server.js
codex mcp get lucho-treasury

Claude Code

claude mcp add lucho-treasury -- node /ABSOLUTE/PATH/TO/lucho-treasury/dist/mcp-server.js
claude mcp get lucho-treasury

Add --scope project before -- if you deliberately want Claude Code to write a shareable project configuration instead of its default local scope.

Claude Desktop, Cursor, and generic stdio hosts

Use this standard MCP server entry in the host's MCP configuration, replacing the absolute path:

{
  "mcpServers": {
    "lucho-treasury": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/lucho-treasury/dist/mcp-server.js"
      ]
    }
  }
}

A copy is available at examples/mcp-config.json. Host-specific config file locations differ, but the command and arguments are the same for any local stdio MCP client.

Add the official Binance Agentic MCP

Lucho and Binance should both appear in the host. In Codex:

codex mcp add binance --url https://agent.binance.com/mcp/agentic
codex mcp login binance
codex mcp list

OAuth should open in the browser. Do not paste access tokens into chat, source files, .env, demo recordings, or receipts. Binance documents an isolated Agentic sub-account and no withdrawal scope; for a hackathon demo, a small or empty Agentic sub-account is still the safer choice.

Ask the host to run the complete workflow

After both servers are visible, start a fresh agent session and use:

Use Binance for one read-only live market observation. Then use Lucho Treasury to plan the fixture
goal in this repository. Do not trade, transfer, subscribe, or invent Earn terms. Clearly label the
live Binance observation and the fictional product fixtures. Explain protected liquidity, true
surplus, rejected products, stress results, and the final ALLOCATE/HOLD/BLOCK decision.

The host should call Binance for the live fact and lucho_plan_treasury for the bounded plan. That visible composition is the key Agent OS demo moment.

Run and verify locally

Install dependencies and run every quality gate:

npm install
npm run check

npm run check performs strict TypeScript checking, compiles the portable server, runs all ten tests—including a real child-process stdio MCP handshake—and produces the machine-readable demo.

Human-readable success path

npm run demo

Expected core result:

Decision: ALLOCATE
Balance: 1000 USDT
Protected liquidity: 900 USDT
True surplus: 100 USDT
Planned allocation: 100 USDT
Stress tests: PASS

Failure path

npm run demo:block

Expected core result: Decision: BLOCK, a protected-liquidity deficit, and 0 USDT allocated.

Machine-readable plan and receipt

npm run demo:json
npm run demo:receipt

The written receipt is permission-restricted and ignored by Git. Public demo inputs remain under fixtures/ and are explicitly labeled fictional.

Safety model

Lucho's core invariants are enforced in code and covered by tests:

1. Execution defaults to off and no financial write tool is exposed.

2. Protected liquidity equals the reserve plus liabilities inside the planning horizon.

3. Allocation never exceeds true surplus, policy cap, concentration cap, or product quota.

4. Capital with an excessive lock-plus-redemption delay is rejected.

5. Mandatory stress failure results in BLOCK.

6. The model-facing review can only reduce or veto the deterministic allocation.

7. A future write must use a fresh token bound to the exact plan and expiration time.

8. Receipts allowlist source metadata and never serialize credentials.

9. Futures, Margin, leverage, withdrawals, and unattended execution are outside scope.

10. APR is treated as variable/risky input, never guaranteed return.

Data modes

The live enum describes receipt/source provenance; it does not mean a live Binance Earn adapter or execution path exists in this repository.

What is real today

These boundaries are intentional. The hackathon submission demonstrates a working, agent-native, read-only decision workflow—not unattended financial execution.

Repository map

lucho-treasury/
├── src/
│   ├── engine.ts          deterministic policy, stress, confirmation, receipts
│   ├── mcp-server.ts      portable MCP tools and orchestration prompt
│   └── cli.ts             reproducible human/JSON demo
├── test/
│   ├── engine.test.ts     policy and safety invariants
│   ├── mcp.test.ts        tool call over in-memory MCP transport
│   └── mcp-stdio.test.ts  compiled server over a real stdio child process
├── fixtures/              fictional, deterministic demo data
├── evidence/              captured read-only Binance Agent OS proof
├── examples/              cross-client MCP configuration
├── SPEC.md                product requirements and acceptance criteria
├── SUBMISSION.md          75–90 second recording and entry runbook
└── IDEAS.md               concept comparison and selection rationale

Submission status

The software is ready to record and submit as a truthful Track A working prototype. The repository is not yet an entered submission until the owner completes the public steps below:

• Build the deterministic agent and portable MCP server.

• Authenticate the official Binance Agentic MCP locally.

• Demonstrate and preserve one real read-only Binance MCP call.

• Pass strict typechecking, build, ten tests, and the demo.

• Commit these final README/MCP portability changes.

• Push the repository to GitHub and make the submission URL accessible.

• Record and upload the 75–90 second demo.

• Follow Binance and repost the official announcement.

• Reply or quote-repost with the Track A video/demo and GitHub link.

• Complete the official survey before September 8, 2026 at 23:59 UTC.

• Save the post URL and submission confirmation as deadline evidence.

See SUBMISSION.md for the exact recording sequence and suggested post copy.

Official references

• Hackathon announcement and entry instructions

• Binance Agent OS

• Binance Agentic MCP documentation

• Binance API catalog

• Model Context Protocol

• MCP TypeScript SDK

License

MIT

Disclaimer

Prototype software for a hackathon. It is not financial advice, does not guarantee yield or principal safety, and should not be used for unattended production execution.