An agent that trades your own account is easy. Fifty lines, one SDK,\u00a0done.<\/p>\n
An agent that trades your account based on what the rest of the market is doing<\/em> is a different build, and on most exchanges it is impossible, because the exchange never tells you what the rest of the market is doing at the grain you would\u00a0need.<\/p>\n Hyperliquid is the exception, and it is the reason to build this here rather than on Binance or on any of the perp venues competing with it<\/a>. The order book runs on its own L1. Every placement, cancel, modify and fill is a signed action sitting in a block, with the wallet attached. Your agent can see who is quoting, who just got liquidated, and how much of the book is real, because all of it is on\u00a0chain.<\/p>\n Getting at it takes more work than a websocket subscribe message. Here is the whole\u00a0build.<\/p>\n Upfront: I work on developer content at Bitquery, and Bitquery sells the indexed Hyperliquid feed used for the read path below. The write path is Hyperliquid\u2019s own free SDK, and I will be specific about where the free native API is the better\u00a0choice.<\/p>\n The instinct is to use one API for everything. That is the first mistake, because reading the market and writing to your account are different problems with different best\u00a0answers.<\/p>\n PathWhat it doesWhat serves it bestWritePlace, cancel and modify your own ordersHyperliquid\u2019s native SDK. Closest to the matching engine, free, canonical.Read (own account)Your positions, fills, marginHyperliquid\u2019s native Info API. Same reason.Read (the market)Who else is positioned, quoting, blowing upAn indexed feed. The native API cannot serve this.DecideTurn the above into an order or a decision to sit stillClaude, with the other three wired in as\u00a0tools<\/p>\n That third row is the one people get wrong, so it is worth being precise about\u00a0why.<\/p>\n Hyperliquid\u2019s public websocket<\/a> gives you l2Book, which is size totalled per price level, up to 20 levels a side. Forty BTC rests at $95,000 and the feed cannot tell you whether that is one order or twenty, whose it is, or whether it got pulled rather than filled. Order-level detail does exist in the native API through orderUpdates and userFills, but only for your own account<\/strong>. Liquidations are the same story: userEvents reports them for one address you already know about, and there is no exchange-wide liquidation feed at\u00a0all.<\/p>\n So if your agent\u2019s job is \u201creact to what other people are doing\u201d, the native API cannot feed it. You need someone to have indexed the chain. That is the read path\u00a0below.<\/p>\n Start here. It is the part that can lose money, and the part to get familiar with\u00a0first.<\/p>\n The write path is the hyperliquid-python-sdk<\/a>, Hyperliquid\u2019s own\u00a0client.<\/p>\n pip install hyperliquid-python-sdk anthropic eth-account requestsimport os, time The order call is positional and easy to get backwards, so here it is spelled\u00a0out:<\/p>\n # exchange.order(name, is_buy, sz, limit_px, order_type, reduce_only=False, cloid=None) Three things in that call matter more than they\u00a0look.<\/p>\n {“limit”: {“tif”: “Alo”}} is post-only. The order is rejected outright if it would cross the spread and take liquidity. For an agent this is the safest default you have, because the worst case of a mispriced quote becomes a rejection instead of a fill at a price you did not intend. Use Gtc when you actually want to rest and cross, Ioc when you want fill-or-kill behaviour.<\/p>\n cloid is your idempotency key, and it is what stops a retry after a network timeout from double-submitting. Derive it from the decision\u00a0itself:<\/p>\n import hashlib Do not reach for Python\u2019s built-in hash() for this, which is the mistake I made first. It is salted per process, so the same decision hashes to a different id after every restart, which is the one property an idempotency key cannot have. An agent loop without a stable cloid will place the same order twice sooner or later, and you will find out during a fast\u00a0market.<\/p>\n And reduce_only=True is worth wiring into any tool whose job is to close rather than open. It is a cheap way to stop “flatten the position” from opening a new one the other\u00a0way.<\/p>\n Cancels come in both flavours, which is why the cloid pays\u00a0off:<\/p>\n exchange.cancel(“ETH”, oid) # by exchange order id The read tools hit an indexed copy of the chain over GraphQL. The technique is the same one I used to track bonding curves and graduations on Pump.fun<\/a>, just pointed at a different chain. The useful property is that the same document works as a query and as a live stream: change query to subscription, drop limit and orderBy, point it at the websocket endpoint, and it\u00a0pushes.<\/p>\n Here is the whole exchange\u2019s fill flow (Trades cube reference<\/a>), which is the feed you would run in a separate process to keep a market picture\u00a0warm:<\/p>\n subscription { No coin filter, so one subscription carries every market. A message looks like\u00a0this:<\/p>\n { Two fields there are worth handing to a model. Direction arrives resolved to Open Short, so the agent is not inferring intent from side plus position state. SizeBefore says the wallet was already short 175,858 ASTER before this fill, which is the difference between “someone sold” and “a large short added”. A negative Fees.Fee is a maker rebate, which is a cheap way to separate passive flow from aggressive.<\/p>\n For book data the cube to know about is BookUpdates<\/a>, which is market-by-order rather than aggregated. One message is one order, carrying its Oid and the Trader.Address that placed it. Oid joins across the schema: the same id appears on Orders as the lifecycle and on Trade.Execution.Oid when it fills, so a single order can be followed end to end. Filter it to one address and you are watching a specific market maker quote and pull in real time (worked examples<\/a>), which is not something a centralised venue will sell you at any\u00a0price.<\/p>\n Claude gets read tools that hit the feed and exactly one write tool that touches the exchange.<\/p>\n import requests The liquidation read\u00a0tool:<\/p>\n @beta_tool Note the return value is a sentence, not a JSON dump. Tool results are input tokens on every subsequent turn of the loop, and a compact string the model reads correctly beats a nested object it has to parse and might\u00a0misread.<\/p>\n The write tool is where the care\u00a0goes:<\/p>\n MAX_NOTIONAL_USD = 250.0@beta_tool Two decisions in there carry the\u00a0weight.<\/p>\n The allowlist and the notional cap are Python, not prompt text. A model asked politely to stay under a cap will stay under it nearly every time, and nearly every time is not a risk control. Anything you would be unhappy to see violated once belongs in an if that runs before the order\u00a0does.<\/p>\n And the tool reports back which of three things happened: resting, filled, or neither. That distinction is not cosmetic, for a reason the next section gets\u00a0to.<\/p>\n The reason argument is doing quiet work too. Requiring the model to state why, in the same call that places the order, gives you an audit log that explains itself six weeks later, and it costs one extra\u00a0field.<\/p>\n You do not have to write the agent loop. The SDK\u2019s tool runner<\/a> drives the call, execute and continue\u00a0cycle:<\/p>\n DESK_RULES = “””You watch two Hyperliquid perp markets and quote passively.Doing nothing is a valid and common answer, and most runs should end that way. thinking={“type”: “adaptive”} lets the model decide how much reasoning a given run deserves, which matters when most runs should end in “nothing to do here”. The cache_control block matters because the rules and tool schemas get resent every turn, and cached reads bill at roughly a tenth of the input\u00a0rate.<\/p>\n Rough cost. Claude Opus 5 is $5 per million input tokens and $25 per million output. A run that reads about 2,000 input tokens and writes about 1,500 comes to roughly five cents. On a five-minute cadence that is 288 runs a day and roughly thirteen dollars, before caching brings the input side down. That number is worth computing for your own cadence before you leave anything running, because the cost of an agent that thinks every minute is not obvious until the invoice\u00a0arrives.<\/p>\n Every one of these cost me a wrong number before I caught it, and each one produces a plausible<\/em> wrong answer rather than an error, which is the dangerous kind.<\/p>\n Counting rows on the liquidation feed<\/a> overstates activity, badly. In one recent\u00a0hour:<\/p>\n fills: 127 A single XPL position unwind produced 16 rows, all in one block, all sharing one execution hash:<\/p>\n 11:27:28.537 Buy size= 5010.0 px=0.10143 One forced unwind ate 16 resting orders at 16 prices, and the feed gives you one row per fill because that is what happened on chain. An agent told \u201c127 liquidations\u201d when the real number is 33 will read a calm hour as a cascade and quote into\u00a0it.<\/p>\n Count distinct execution hashes:<\/p>\n fills: count Fix it at the tool boundary where you can see it. A model handed a number labelled count will reason confidently about the wrong quantity and will not flag that it is confused.<\/p>\n Count BTC order events by status over ten minutes and the shape is startling:<\/p>\n badAloPxRejected 1,848,618 83.6% Eighty-four percent of everything that happens to a BTC order is badAloPxRejected, and one tenth of one percent is a fill. Checking what those rejected orders were, every one is a post-only limit order, split near evenly between buys and\u00a0sells:<\/p>\n Limit Buy Tif=Alo 478,047 That is the quoting race on the most liquid market on the exchange: market makers trying to post at the touch, losing, and getting bounced. Two million of those in ten minutes. ETH is the same shape, 78.6% rejected and 0.06%\u00a0filled.<\/p>\n Your agent is posting Alo orders into exactly that. Rejection is the normal<\/em> outcome, not the exception, which is why the write tool above distinguishes resting from filled from neither. An agent that assumes its quote is live when the matching engine bounced it will keep reasoning about a position it does not have, and will hedge or size against a\u00a0phantom.<\/p>\n It also breaks any activity metric you build. If you compute a cancel-to-fill ratio from a bare event count, 84% of your denominator on BTC never reached the\u00a0book.<\/p>\n HIP-3 lets outside builders deploy their own perp markets on Hyperliquid, under a namespace prefix, trading in the same infrastructure. A lot of them are tokenized equities, which is the same land grab Arcus is running at the dYdX team<\/a>. There are currently 279 live across 10 deployers, the largest being xyz with 119 markets, then para with 33 and hyna with\u00a025.<\/p>\n Query mark prices<\/a> filtered to the symbol\u00a0BTC:<\/p>\n flx:BTC 91470.2 Three builders, three markets called BTC, three prices more than twenty thousand dollars apart, each on its own oracle. If your ingestion keys on Symbol, an agent can read a price from one market and send an order to another. Key on CoinRaw, which carries the full namespace:symbol identifier.<\/p>\n No data provider invented this. It falls out of permissionless market listing, and it will bite anyone who assumes symbols are\u00a0unique.<\/p>\n An agent that only reads the market and never reads itself will drift. Two things need reconciling at the top of every\u00a0run.<\/p>\n The real position, from the native API rather than from\u00a0memory:<\/p>\n @beta_tool And the resting orders, so the agent does not stack five quotes across five runs because each run forgot the last. info.open_orders(address) covers this, and a cheap policy that works well is to cancel everything the agent placed at the start of a run and requote from a clean\u00a0book.<\/p>\n Feed both in as tools rather than as prompt text. The model then reads current state at the moment it needs it, instead of trusting a snapshot you pasted in at the top of the turn that may already be\u00a0stale.<\/p>\n constants.TESTNET_API_URL is not decoration. Moving off it should be a separate, deliberate commit made after the thing has run for a couple of weeks and surprised you at least\u00a0once.<\/p>\n Some specifics that are worth more than a paragraph of general\u00a0caution.<\/p>\n Expect it to do nothing.<\/strong> Exchange-wide, Hyperliquid liquidates in the low tens of positions an hour, and BTC alone can go four hours without a single one. An agent gated on BTC liquidations will correctly sit still on most runs. That is the right way round to test it: watch it decline to act on a quiet market before you point it at a busy\u00a0one.<\/p>\n Keep the kill switch outside the process.<\/strong> A supervisor you can kill -9, or an exchange-side cancel-all you can fire by hand, beats any instruction in a system prompt. The system prompt is guidance. The process boundary is a guarantee.<\/p>\n Log the tool calls, not just the outcome.<\/strong> An agent that placed a strange order is only debuggable if you can replay what it saw when it decided. Arguments and results, every call, including the refusals from your own guardrails, since a spike in refusals is the earliest signal that the reasoning has gone somewhere odd.<\/p>\n Cap what one run can do, not just one order.<\/strong> The notional cap above limits a single order. A run that places one order twenty times is still within that cap and nowhere near\u00a0safe.<\/p>\n Where this approach is weaker than the alternatives, plainly. The indexed feed sits behind the matching engine by an indexing step, so anything reacting in single-digit milliseconds belongs on the native websocket instead. The GraphQL window is a rolling thirty days or so, which covers live trading and recent-history checks but not a multi-year backtest. And the highest-volume cubes, Orders and BookUpdates, run to hundreds of millions of rows a day on a busy market, so filtered scans over long windows time out; keep interactive windows to an hour and accumulate anything longer in your own\u00a0store.<\/p>\n This is plumbing. Nothing above tells you what to trade or suggests you should, and a language model wired to a market data feed is not an edge. It is a way to act on one you already have, and equally a way to act on a bad idea faster than you could by\u00a0hand.<\/p>\n What Hyperliquid genuinely changes is the input. On a centralised venue your agent reasons about price and its own fills, because that is all the exchange will sell you. Here it can reason about who is positioned where, which quotes are real, and who just got carried out, because the book is on a public chain and the wallet is attached to every\u00a0order.<\/p>\n The reasoning layer is the easy part now. Getting clean, correctly counted market state into it is the work, and three of the traps are\u00a0above.<\/p>\n Docs for the read-path queries: <\/em>Hyperliquid API on Bitquery<\/em><\/a>. The native API and SDK: <\/em>hyperliquid.gitbook.io<\/em><\/a>. Every figure was pulled live on 4 September 2026 and will have moved by the time you read\u00a0this.<\/em><\/p>\n Disclosure: I work on developer content at Bitquery, which sells the indexed feed used for the read path. The write path is Hyperliquid\u2019s own free SDK, and the sections on latency, history depth and query limits are there because they are real constraints.<\/em><\/p>\n Building an AI Crypto Trading Bot on Hyperliquid<\/a> was originally published in Coinmonks<\/a> on Medium, where people are continuing the conversation by highlighting and responding to this story.<\/p>","protected":false},"excerpt":{"rendered":" Claude decides, the Hyperliquid SDK executes, an indexed feed supplies the market. Plus the three ways the data will quietly lie to your agent, all of which I\u00a0hit. An agent that trades your own account is easy. Fifty lines, one SDK,\u00a0done. An agent that trades your account based on what the rest of the market […]<\/p>\n","protected":false},"author":0,"featured_media":223285,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-223284","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-interesting"],"_links":{"self":[{"href":"https:\/\/mycryptomania.com\/index.php?rest_route=\/wp\/v2\/posts\/223284"}],"collection":[{"href":"https:\/\/mycryptomania.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mycryptomania.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/mycryptomania.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=223284"}],"version-history":[{"count":0,"href":"https:\/\/mycryptomania.com\/index.php?rest_route=\/wp\/v2\/posts\/223284\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/mycryptomania.com\/index.php?rest_route=\/wp\/v2\/media\/223285"}],"wp:attachment":[{"href":"https:\/\/mycryptomania.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=223284"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mycryptomania.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=223284"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mycryptomania.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=223284"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}The architecture: three paths, three\u00a0tools<\/h3>\n
The write\u00a0path<\/h3>\n
from eth_account import Account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants
from hyperliquid.utils.types import CloidBASE_URL = constants.TESTNET_API_URL # change this last, and deliberatelywallet = Account.from_key(os.environ[“HL_SECRET_KEY”])
address = os.environ[“HL_ACCOUNT_ADDRESS”]exchange = Exchange(wallet, BASE_URL, account_address=address)
info = Info(BASE_URL, skip_ws=True)<\/p>\n
result = exchange.order(
“ETH”, True, 0.2, 1100.0,
{“limit”: {“tif”: “Alo”}},
cloid=Cloid.from_int(1734029481),
)<\/p>\n
from hyperliquid.utils.types import Cloiddef decision_cloid(*parts) -> Cloid:
“””Stable 16-byte client order id derived from the decision.”””
key = “|”.join(str(p) for p in parts).encode()
return Cloid.from_str(“0x” + hashlib.sha256(key).hexdigest()[:32])<\/p>\n
exchange.cancel_by_cloid(“ETH”, cloid) # by your own id<\/p>\nThe read\u00a0path<\/h3>\n
Hyperliquid {
Trades {
Block { Time }
Trade {
Market { Symbol CoinRaw Kind }
Execution { Price Size Side Direction IsAggressor Oid }
Fees { Fee FeeToken }
Position { Leverage IsCross SizeBefore }
Trader { Address }
}
}
}
}<\/p>\n
“Block”: { “Time”: “2026-09-04T11:19:51.137023Z” },
“Trade”: {
“Market”: { “Symbol”: “ASTER”, “CoinRaw”: “ASTER”, “Kind”: “perp” },
“Execution”: {
“Price”: “0.75677”, “Size”: “175.0”, “Side”: “Sell”,
“Direction”: “Open Short”, “IsAggressor”: true, “Oid”: “535941127746”
},
“Fees”: { “Fee”: “0.01907”, “FeeToken”: “USDC” },
“Position”: { “Leverage”: 5, “IsCross”: true, “SizeBefore”: “-175858.0” },
“Trader”: { “Address”: “0xa33a4a057334c7811ad5f45f3c4f0dfa3d081ff8” }
}
}<\/p>\nWiring the\u00a0tools<\/h3>\n
from anthropic import Anthropic, beta_toolclient = Anthropic()
BQ_URL = “https:\/\/streaming.bitquery.io\/graphql”
BQ_AUTH = {“Authorization”: f”Bearer {os.environ[‘BITQUERY_TOKEN’]}”}
ALLOWED_MARKETS = {“BTC”, “ETH”}def bq(query: str, variables: dict) -> dict:
r = requests.post(BQ_URL, headers=BQ_AUTH,
json={“query”: query, “variables”: variables}, timeout=30)
r.raise_for_status()
payload = r.json()
if “errors” in payload:
raise RuntimeError(payload[“errors”][0][“message”])
return payload[“data”][“Hyperliquid”]<\/p>\n
def recent_liquidations(symbol: str, minutes: int = 60) -> str:
“””Count Hyperliquid liquidations on one market over a recent window. Returns distinct liquidation events, the wallets hit, and the raw fill
count. Prefer the liquidation count over the fill count. Args:
symbol: Market symbol. Must be BTC or ETH.
minutes: Lookback in minutes, 1 to 60.
“””
if symbol not in ALLOWED_MARKETS:
return f”refused: {symbol} is not in the allowlist”
minutes = max(1, min(int(minutes), 60)) query = “””
query ($sym: String!, $mins: Int!) {
Hyperliquid {
PerpLiquidations(where: {
Liquidation: {Market: {Symbol: {is: $sym}}}
Block: {Time: {since_relative: {minutes_ago: $mins}}}
}) {
fills: count
liquidations: count(distinct: Liquidation_Execution_Hash)
wallets: count(distinct: Liquidation_LiquidatedUser)
}
}
}
“””
rows = bq(query, {“sym”: symbol, “mins”: minutes})[“PerpLiquidations”]
if not rows:
return f”{symbol}: 0 liquidations in the last {minutes}m”
r = rows[0]
return (f”{symbol}: {r[‘liquidations’]} liquidations hitting “
f”{r[‘wallets’]} wallets in the last {minutes}m “
f”({r[‘fills’]} individual fills)”)<\/p>\n
def place_post_only_order(symbol: str, is_buy: bool, size: float,
limit_price: float, reason: str) -> str:
“””Place one post-only limit order on Hyperliquid. Post-only means the exchange rejects the order outright if it would
cross the spread. Rejection is normal and expected, not an error. Args:
symbol: Market symbol. Must be BTC or ETH.
is_buy: True to bid, False to offer.
size: Contracts. Notional is capped server-side by this tool.
limit_price: Limit price in USD.
reason: One sentence on why, recorded in the audit log.
“””
if symbol not in ALLOWED_MARKETS:
return f”refused: {symbol} is not in the allowlist”
notional = size * limit_price
if notional > MAX_NOTIONAL_USD:
return (f”refused: ${notional:,.0f} notional exceeds “
f”the ${MAX_NOTIONAL_USD:,.0f} cap”) cloid = decision_cloid(symbol, is_buy, round(limit_price, 2),
int(time.time() \/\/ 60))
audit.write(symbol, is_buy, size, limit_price, reason, str(cloid)) result = exchange.order(symbol, is_buy, size, limit_price,
{“limit”: {“tif”: “Alo”}}, cloid=cloid)
if result.get(“status”) != “ok”:
return f”exchange rejected the request: {result}” status = result[“response”][“data”][“statuses”][0]
if “resting” in status:
return f”resting on the book, oid {status[‘resting’][‘oid’]}”
if “filled” in status:
return f”filled immediately: {status[‘filled’]}”
return f”not resting, no fill: {status}”<\/p>\nThe loop<\/h3>\n
Never chase price. Place at most one order per run.
A post-only rejection means your price crossed the spread. Do not resubmit it
at a crossing price; either move the price passive or stand down.
Liquidation counts are events, not fills. Do not treat a fill count as activity.”””runner = client.beta.messages.tool_runner(
model=”claude-opus-5″,
max_tokens=16000,
thinking={“type”: “adaptive”},
output_config={“effort”: “high”},
system=[{
“type”: “text”,
“text”: DESK_RULES,
“cache_control”: {“type”: “ephemeral”},
}],
tools=[recent_liquidations, open_position, place_post_only_order],
messages=[{“role”: “user”, “content”:
“Check BTC. If liquidations are elevated versus a normal hour, consider “
“quoting passively on the side that just got run over. Otherwise do nothing.”
}],
)for message in runner:
log(message)<\/p>\nThree ways the data will lie to your\u00a0agent<\/h3>\n
It thinks one liquidation is\u00a0sixteen<\/h4>\n
liquidations: 33
wallets: 33
markets: 11<\/p>\n
11:27:28.537 Buy size= 490.0 px=0.10142
11:27:28.537 Buy size= 11059.0 px=0.10149
11:27:28.537 Buy size= 28173.0 px=0.10160
… (12 more)<\/p>\n
liquidations: count(distinct: Liquidation_Execution_Hash)
wallets: count(distinct: Liquidation_LiquidatedUser)<\/p>\nIt thinks its quote is resting when it was\u00a0rejected<\/h4>\n
open 150,206 6.8%
canceled 131,269 5.9%
perpMarginRejected 43,063 1.9%
iocCancelRejected 20,579 0.9%
tooManyOpenOrdersRejected 14,775 0.7%
filled 1,608 0.1%
TOTAL 2,210,732<\/p>\n
Limit Sell Tif=Alo 431,349<\/p>\nIt trades the wrong\u00a0BTC<\/h3>\n
hyna:BTC 76888.0
cash:BTC 70000.0<\/p>\nState between\u00a0runs<\/h3>\n
def open_position(symbol: str) -> str:
“””Report the agent’s actual open position on one market. Args:
symbol: Market symbol. Must be BTC or ETH.
“””
state = info.user_state(address)
for entry in state[“assetPositions”]:
p = entry[“position”]
if p[“coin”] == symbol:
return (f”{symbol}: size {p[‘szi’]}, entry {p.get(‘entryPx’)}, “
f”unrealized {p[‘unrealizedPnl’]}”)
return f”{symbol}: flat”<\/p>\nRunning it without losing\u00a0money<\/h3>\n
What this is and is\u00a0not<\/h3>\n