# Vaultomate — machine-readable integration guide (llms.txt)

> Vaultomate (https://vaultomate.xyz) turns systematic trading strategies into on-chain funds
> on Hyperliquid. The strategy runs on the USER'S infrastructure (TradingView, Python, or an AI
> agent) and sends trade DECISIONS to Vaultomate's signal API. Execution happens inside a caged
> vault (audited contracts: Lagoon ERC-7540 + Gnosis Safe + Zodiac Roles): the trading key can
> trade but can NEVER withdraw funds. Every fill/loss/fee/skip lands on a public, un-fakeable
> record page computed from blockchain data. This file is self-contained: an AI assistant that
> reads it can integrate a user's strategy end-to-end.

## REQUIREMENTS (check before starting — exact, measured from the deploy plan)
- A wallet on HyperEVM MAINNET — chain id 999, RPC https://rpc.hyperliquid.xyz/evm
- >= $18 USDC on HyperEVM (token 0xb88339CB7199b77E23DB6E890353E22632Ba630f):
  $3 vault operations float + $15 minimum trading capital (capital stays the user's)
- ~0.03 HYPE on HyperEVM (0.02 gas-funds the vault's bot+oracle + ~10 tx fees; ~$2 buffer is plenty).
  One-time: after deploy the platform's gas keeper monitors and refills vault gas automatically.
- TradingView route only: TradingView PLUS plan or higher + 2FA (verified 2026-07-06 against a live alert: Essential does NOT include webhooks; Plus is the floor)
- Humans: https://vaultomate.xyz/create (browser wallet signs ~10 txs). Agents: see API ONBOARDING below.

## API ONBOARDING (agents/scripts — no browser needed; fund the wallet FIRST or txs revert)
1. POST /v1/onboard/txs {"name","symbol","manager_wallet","perf_bps"} ->
   ordered txs[] (to, data, value) + predicted {safe, vault, roles_module} + bot/oracle
   addresses (keys platform-held; the cage means they can trade, never withdraw).
   Sign & send each tx IN ORDER with the manager wallet (chain 999). Each tx carries a
   resume_check — re-running the plan skips completed steps automatically.
   IMPORTANT gate: before the register_bot step, poll spotClearinghouseState (HL info API)
   until the Safe's Core account shows a balance — Hyperliquid consumes $1 of the first
   bridge as a one-time account fee; register too early and the attempt is wasted.
2. GET /v1/onboard/state/{wallet} — resume state for a wallet (in_flight / completed).
3. POST /v1/onboard/complete {"symbol","manager_wallet","safe","vault","bot"} — runs the
   custody verifies (builder cap, agent registration, owner) and returns THE API KEY ONCE.
4. POST /v1/onboard/seed {"manager_wallet","amount_usd">=15} -> approve + requestDeposit txs
   to sign. Shares mint at the next daily settlement (~15:30 UTC).
5. Send a shadow signal (see SIGNAL API), then flip live: POST /v1/vault/mode {"mode":"live"}
   with the Bearer key. Gates: >=1 shadow signal seen, custody verifies pass, equity >= $10.

## COSTS & YOUR REVENUE (exact — the whole fee picture, one place)
BUILDER FEE (per fill, entry/exit split; on-chain hard cap 5.0 bps per fill):
- ENTRY fills -> platform builder, 2.5 bps -> us. This is our monetization.
- EXIT fills  -> the MANAGER's builder at their markup (0-3.5 bps, they set it) ->
  the manager's wallet, paid by Hyperliquid directly. Nobody invoices anybody.
- These are SEPARATE fills with SEPARATE builders — NOT a 2.5+3.5 split on one fill.
- Manager markup requires >=$100 in the manager's HL perps to accrue; below that,
  or if unset, exits fall back to the platform's 2.5 bps.
- CAVEAT: a stop-loss rests on the book from entry, so STOP-TRIGGERED exits carry
  the platform builder — the manager's markup earns on SIGNAL-closed exits only.
EXCHANGE FEE (Hyperliquid's, not ours): ~4.5 bps taker / 1.5 bps maker per fill.
PERFORMANCE FEE (the manager's main revenue): 0-30%, manager sets it, on gains
  above the high-water mark, minted as shares at settlement (10% of it to Lagoon).
DEPLOY: ~$5 gas (to the network) + $15 min activation capital (stays yours, redeemable).
NONE: no management fee, no subscription, no listing fee. Records are ALWAYS net of everything.

## SIGNAL API — the one contract
POST https://vaultomate.xyz/v1/signal
Header: Authorization: Bearer <API_KEY>
Body (JSON, unknown fields rejected):
  target     "long" | "short" | "flat"     REQUIRED — declarative TARGET STATE, not an action
  coin       e.g. "SOL", "BTC"             REQUIRED
  order      "market"                       required for entries
  risk_pct   e.g. 1.0                       entries: % of vault equity LOST if the stop hits.
                                            Position size is DERIVED: risk$ / stop-distance.
  sl         absolute stop price            REQUIRED on every entry (enforced on-exchange)
  tp         absolute take-profit           optional
  client_id  unique string                  REQUIRED — idempotency key; retries are safe
  ts         unix seconds                   entries: freshness guard (~10s max age)
Semantics: entries are price-guarded (if the market moved past the slippage guard the signal is
SKIPPED, never chased — response says so). Exits self-heal. Every position carries an on-exchange
stop. Responses are synchronous JSON: outcome (shadow|executed|skipped|rejected|duplicate) + note.
New vaults start in SHADOW mode (full validation+sizing, no order) until flipped live.

Python example:
  import requests, time
  requests.post("https://vaultomate.xyz/v1/signal",
      headers={"Authorization": "Bearer vf_YOUR_KEY"},
      json={"target":"long","coin":"SOL","order":"market","risk_pct":1.0,
            "sl":78.6,"ts":time.time(),"client_id":f"my-{int(time.time()*1000)}"})
Flatten: {"target":"flat","coin":"SOL","client_id":"..."}

## TRADINGVIEW route (no code)
POST https://vaultomate.xyz/v1/signal/tv   (API key rides in the body — TradingView can't set HTTP headers)
Alert message template (paste into the TradingView alert "Message" box; webhook URL above):
  {"api_key":"vf_YOUR_KEY","position":"{{strategy.market_position}}","ticker":"{{ticker}}",
   "risk_pct":1.0,"sl_pct":2.0,"client_id":"{{timenow}}"}
Notes: {{strategy.market_position}} (flat|long|short AFTER the order) maps 1:1 to target.
sl_pct converts to an absolute stop from the live mark at receipt; an exact "sl" wins if sent.
Keep each {{placeholder}} ALONE inside its quotes (…"ticker":"{{ticker}}"…, not glued to text):
TradingView's edit-box JSON linter false-warns on glued placeholders — the alert still fires,
but the clean form avoids the scary orange warning. {{timenow}} renders as an ISO timestamp
string (verified against a live TradingView alert, 2026-07-06), which is fine for client_id.
Requires TradingView Plus or higher (Essential does NOT include webhooks — verified 2026-07-06).
Chart HYPERLIQUID:-prefixed symbols (TradingView carries Hyperliquid's native data, live since 2026-07-02) — e.g. HYPERLIQUID:SOLUSDC.P.

## SUPPORTED MARKETS
- LIVE trading path today: SOL, BTC, ETH perpetuals (USDC-margined, on Hyperliquid).
- "coin" is the PLAIN symbol: "SOL" — never a pair or ticker ("SOLUSDC.P" is wrong here).
- TradingView tickers normalize automatically: HYPERLIQUID:SOLUSDC.P, SOLUSDT, BTCUSD.P
  etc. all resolve to the plain coin — chart whatever feed you like, we extract the coin.
- Shadow mode accepts any Hyperliquid-listed coin (so you can rehearse), but flags coins
  outside the live set in the outcome note. A live vault REJECTS them until supported.
- More markets ship measured by demand — tell us which one you need.

## EXCHANGE SEMANTICS (Hyperliquid — different from MT5/most brokers)
- ONE NET POSITION PER COIN. Hyperliquid nets everything: no hedged long+short on the
  same coin, no separate tickets. Declarative targets map to this exactly.
- Same-direction entry while already positioned = idempotent NO-OP (skipped; adds not
  supported yet). Direction flip = send target "flat" first, then the new entry.
- Stops/TPs rest exchange-side, reduce-only; they auto-cancel when the position closes.

## EXECUTION COSTS (transparent on every record page)
- Current execution: IOC market orders = TAKER on every fill. Hyperliquid tier-0:
  taker 4.5 bps, maker 1.5 bps. All-in today: 4.5 exchange + 2.5 builder = 7.0 bps/fill.
- Every fill on a record page is labeled MAKER or TAKER (from the fill's `crossed`
  field — public data, verify it yourself). The record's Execution section shows the
  maker/taker mix per side, all-in bps, and volume traded.
- Roadmap: maker-biased entries (ALO/post-only at the touch — the method our parent
  fund trades with) save ~3 bps/fill where the strategy can wait for a passive fill.
- Far future: HYPE staking discounts can cut exchange fees per address; not planned yet.

## MANAGER REVENUE — THE ENTRY/EXIT BUILDER SPLIT
- Two revenue streams: the PERFORMANCE FEE you set (0-30%, high-water mark) and an
  optional VOLUME MARKUP (0-3.5 bps) on exit fills.
- How the markup pays: exit fills carry YOUR wallet as the Hyperliquid builder — the
  exchange credits your markup per fill, directly and continuously. Nobody invoices anybody.
- Entry fills carry the platform's 2.5 bps. Total builder fee is hard-capped on-chain at
  5 bps by the approval your wallet signs at deploy.
- Eligibility (Hyperliquid rule, not ours): your wallet must hold >=$100 in HL perps to
  accrue builder fees. Below it, exits fall back to the platform fee and the signal
  response says so.
- Caveat: STOP-TRIGGERED exits carry the platform fee (the resting stop is placed with
  the entry) — your markup applies to signal-closed exits.
- Watch it: GET /v1/vault/{vault_address}/revenue (public). Claim it: on Hyperliquid
  (accrued fees -> claim -> spot USDC in your account).
- Depositor view: the record page terms disclose the split; returns are always net of
  ALL fees — a markup that hurts the record hurts the manager first.

## RISK PROFILES (chosen at vault creation; shown on the record page; platform-enforced)
- conservative: risk <=1.25%/trade · stop >=0.50% away · leverage <=3x
- standard (default): risk <=2.5%/trade · stop >=0.15% away · leverage <=10x
- aggressive: risk <=5%/trade · stop >=0.05% away · leverage <=20x
Universal, every profile: stops mandatory + exchange-side; wrong-side stops rejected;
caps are server-side constants (not tamperable via the API). Coming: 5-12% aggregate
risk budget per profile + daily -10% circuit breaker (entries pause, exits always work).

## VERIFY / OBSERVE
- Signal log (every signal + outcome incl. skips): GET /v1/vault/{vault_address}/log
- Public record page: https://vaultomate.xyz/v/{symbol}  (numbers computed from chain data)
- Share card: /v/{symbol}/card.png

## SAFETY MODEL (facts, verifiable on-chain)
- The API key / trading key can ONLY trade. It cannot withdraw, transfer, or change permissions
  (Zodiac Roles cage on a Gnosis Safe; verify on the record page's cage links).
- Every entry requires a stop; stops rest on-exchange, not in software.
- Records show losses and skipped signals; dead vaults stay public. Capital at risk.