Docs · agents

Run a betting agent on Variance Vault.

Variance Vault is a permissionless parametric variance exchange on HyperEVM. AI agents place bets autonomously through a Sponge wallet plus a published MCP server. Five minutes from nothing to a real on-chain bet.

Quickstart

Five steps to a live bet.

Time: ~5 minutes. Cost: gas (a few cents in HYPE) plus whatever you choose to stake.

01
Create a Sponge agent.
Sponge gives every agent its own self-custodied EVM key. The same address works on Ethereum, Base, HyperEVM, Arbitrum, and more — Sponge picks the right chain at sign-time.
```
npx spongewallet init --name my-betting-agent
```
Copy the sponge_live_… API key it prints and the HyperEVM address. You'll use both below.
02
Fund the agent's HyperEVM address.
Send USDC (for stakes) and HYPE (for gas) to the agent's HyperEVM address — the address Sponge printed in step 1, not any contract address on this page. Each bet costs the agent ~0.0005 HYPE in gas (approve + place; the keeper pays for the settle), so 0.05 HYPE comfortably covers ~100 bets. USDC is whatever you choose to stake.
If your agent's USDC is on Base, Arbitrum, or another chain Sponge supports, its built-in bridge tool can route to HyperEVM in one call. Otherwise any wallet or exchange that supports HyperEVM USDC works. Token contract addresses live in the Contract reference section below if you need them for low-level integration; the agent itself doesn't.
03
Request access.
Variance Vault is invite-only during Phase 1 — every address must be allowlisted on-chain before its first call lands. Submit your agent's HyperEVM address below; the request lands in the same admin queue Phase 1 invitees use, and approvals usually clear within the day.
Your contact emailWhere Finn replies if anything's off.Agent's HyperEVM addressThe 0x address Sponge printed when you ran spongewallet init.One-line descriptionWhat's this agent for? 5–280 chars.
04
Install the MCP server.
On Claude Code, one command — no file editing, no restart:
```
claude mcp add variance-vault -s user \
  -e SPONGE_API_KEY=sponge_live_xxx \
  -- npx -y @variancevault/agent-mcp
```
-s user registers the server at user scope so it's available in every Claude Code session, not just the current project. Replace sponge_live_xxx with the API key Sponge printed in step 1.
For other MCP-compatible runtimes (Cursor, Claude Desktop, custom harnesses), drop this equivalent block into your runtime's MCP config:
```
{
  "mcpServers": {
    "variance-vault": {
      "command": "npx",
      "args": ["-y", "@variancevault/agent-mcp"],
      "env": {
        "SPONGE_API_KEY": "sponge_live_xxx"
      }
    }
  }
}
```
Published as @variancevault/agent-mcp on npm.
05
Prompt the agent.
The MCP exposes three tools — get_state, place_bet, and check_bet. Schemas are below; the agent reads them automatically. A prompt as terse as this works:
```
You have access to the variance-vault MCP and a Sponge wallet
with some USDC. Risk 10 cents to make 30 cents — be smart
about it. Report when you're done.
```
Agent · Phase 1 limits
Every place_bet call's stake_usdc must be ≤ $100 — the contract reverts above that. Open (still-settling) bets count toward the same cap, so if you run bets in parallel their stakes must also sum to ≤ $100. The live cap value is in get_state's deposit_cap_usdc field; read it before sizing.

Tools

The MCP surface.

Three tools is enough for any betting strategy. Every value returned by every tool is fresh from chain state at call time.

get_state

Returns the agent's HyperEVM balance, allowlist status, and the vault's live parameters: TVL, house edge in bps, the 1% per-bet payout cap (and its dollar value as max_gross_payout_per_bet_usdc, the most useful single field for sizing a stake), the per-user deposit cap, and the next bet id. Call this first so the agent knows what it can stake.

place_bet

Submits USDC.approve(vault, stake), waits for confirmation, submits placeBet(stake, win_prob_bps, 0, win_msg, loss_msg), and waits for the BetSettled event from the keeper — typically ~5 seconds after placeBetlands (2-block settle delay plus the keeper round-trip). Returns the full receipt: bet id, outcome, gross payout, net P&L, post-bet balance, and all three tx hashes.

Hard limits enforced by the contract: stake_usdc must be ≤ deposit_cap_usdc ($100 during Phase 1, read live via get_state), and the implied gross payout (stake × 10000 / win_prob_bps) must be ≤ max_gross_payout_per_bet_usdc. Open bets count toward the same $100 — parallel stakes must sum to ≤ the cap.

Rare timeout branch: if the keeper's BetSettled event doesn't arrive before the polling window expires, the call returns { status: 'pending', bet_id, place_tx } instead of throwing. The bet is on-chain and the keeper will still settle it — do NOT retry place_bet (you'd double-stake). Call check_bet(bet_id) a few seconds later to read the outcome.

Arguments

stake_usdc: string; USDC decimal string. Max 6 decimals. E.g. "0.10".
win_prob_bps: integer; Win probability in basis points, 1–9999. 5000 = 50% (~2× payout). 1000 = 10% (~10×). 9000 = 90% (~1.11×).
win_message: string?; Optional 1–64 char tag emitted with the bet.
loss_message: string?; Optional 1–64 char tag emitted with the bet.

check_bet

Reads a single bet's on-chain state. Returns the bettor, stake, max gross payout, win probability, commit block, and status (open / settled / voided). If settled, includes the outcome, payout, and settle tx hash. Useful for inspecting other users' bets or reviewing the agent's own history. If you're polling a just-placed bet, wait ~5 seconds before the first check — sooner will still read open.

Arguments

bet_id: integer; Numeric bet id. Most recent is `next_bet_id − 1`.

Contract

On-chain addresses.

vault proxy: 0xc1a018fd2995EBc7890dfFf196dEC2cEE75C7dbE
USDC: 0xb88339CB7199b77E23DB6E890353E22632Ba630f
chain id: 999 (HyperEVM mainnet)
public RPC: https://rpc.hyperliquid.xyz/evm
explorer: https://app.hyperliquid.xyz/explorer
source: /contract/VarianceVault.sol (the full Solidity, served from this domain)

The contract is UUPS upgradeable; integrate against the proxy. Storage layout is preserved across upgrades. Implementation rotates — read the proxy's implementation() if you care.

Math

How payouts work.

For a bet with stake S and win probability p (= win_prob_bps / 10000), the contract pays a fixed gross payout on a win:

gross_payout = S × (1 / p) × (1 − 0.015)

The 1 − 0.015 is the LP edge — 150 bps that accrues to the pool over many bets and shows up as yield on share price. Losses pay zero; the stake is forfeit to the pool.

Per-bet gross payout is capped at 1.00% of pool net assets. With a $1,400 TVL the agent can structurally not lose the LPs more than ~$14 in a single settle — the cap fixes the LPs' worst-case drawdown.

Settlement is two-phase. placeBet commits at block N; anyone can call settle(betId) at block N + 2 (~0.4s later). Outcome is:

keccak256(blockhash(N+2), betId, bettor) mod 10000 < win_prob_bps → win

A permissionless keeper auto-settles in production, so the agent doesn't need to call settle itself — the place_bet tool waits for the keeper to emit BetSettled and returns the result.

References

Where everything lives.

MCP server: @variancevault/agent-mcp on npm
Contract source: /contract/VarianceVault.sol — full Solidity, served from this domain
Sponge SDK: docs.paysponge.com — the wallet layer.

Run a betting agent on Variance Vault.

Five steps to a live bet.

Create a Sponge agent.

Fund the agent's HyperEVM address.

Request access.

Install the MCP server.

Prompt the agent.

The MCP surface.

On-chain addresses.

How payouts work.

Where everything lives.