Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Perps venue module: Hyperliquid perpetuals, read through the keyless public
// info API and traded through a per-agent API wallet.
//
// Hyperliquid is an EVM-style venue, not a Solana program, so it is the
// secondary leg beside the Solana venues (Phoenix, Jupiter). Collateral is USDC
// held in the owner's Hyperliquid account, which the owner funds on Hyperliquid
// itself; the platform never moves it. The agent trades with an API wallet: a
// separate key the owner approves on Hyperliquid, which can place and cancel
// orders but cannot withdraw. See ./hyperliquid-signing.js.
//
// Read paths (markets, books, funding, account) are keyless and live. The
// `buildOrderAction` and `buildCancelAction` builders return the exchange action
// the signing module signs; this module never holds a key.
import { hlInfo } from '../hyperliquid.js';
import { perpsError } from './errors.js';
import { num, round, memo, normalizeBook, estimateFill, projectPosition } from './venue-common.js';
import { formatPrice, formatSize } from './hyperliquid-signing.js';
export const id = 'hyperliquid';
export const label = 'Hyperliquid (API wallet)';
export const collateral = Object.freeze({ asset: 'USDC', decimals: 6 });
export const chain = 'hyperliquid';
export const execution = 'api_wallet';
export const capabilities = Object.freeze({
order_types: Object.freeze(['market', 'limit']),
conditional_orders: false,
trader_account: false,
deposit_withdraw: false,
cancel: true,
order_book: true,
});
const MARKETS_TTL_MS = 4_000;
const BASE_TAKER_FEE = 0.00045;
const BASE_MAKER_FEE = 0.00015;
/** Wrap an info read so a venue failure surfaces as a designed, retryable error. */
async function info(what, body) {
try {
return await hlInfo(body);
} catch (err) {
throw perpsError(
502,
'venue_unavailable',
`Hyperliquid did not answer while trying to ${what}. Nothing was signed; retry in a moment.`,
{ cause: String(err?.message || err).slice(0, 240) },
);
}
}
/** Accept "BTC", "btc", "BTC-PERP" and "BTC/USD" for the same market. */
export function normalizeSymbol(symbol) {
return String(symbol || '')
.trim()
.replace(/[-/](PERP|USD|USDC)$/i, '');
}
/** Pure: the (meta, assetCtxs) pair into the interface's market rows. */
export function normalizeMarkets(payload) {
const [meta, ctxs] = Array.isArray(payload) ? payload : [null, []];
return (meta?.universe || [])
.map((u, index) => {
const ctx = ctxs[index] || {};
const mark = num(ctx.markPx);
const prev = num(ctx.prevDayPx);
const oi = num(ctx.openInterest);
const maxLev = num(u.maxLeverage) || 1;
return {
symbol: u.name,
name: u.name,
kind: 'crypto',
status: u.isDelisted ? 'delisted' : 'active',
mark_price: mark,
index_price: num(ctx.oraclePx),
change_24h_pct:
mark != null && prev ? round(((mark - prev) / prev) * 100, 3) : null,
funding_rate_hourly_pct:
num(ctx.funding) != null ? round(num(ctx.funding) * 100, 8) : null,
funding_rate_8h_pct:
num(ctx.funding) != null ? round(num(ctx.funding) * 800, 8) : null,
funding_apr_pct:
num(ctx.funding) != null ? round(num(ctx.funding) * 24 * 365 * 100, 4) : null,
open_interest: oi,
open_interest_usd: oi != null && mark != null ? round(oi * mark, 2) : null,
volume_24h_usd: num(ctx.dayNtlVlm),
max_leverage: maxLev,
initial_margin_rate: round(1 / maxLev, 8),
maintenance_margin_rate: round(1 / (2 * maxLev), 8),
taker_fee_rate: BASE_TAKER_FEE,
maker_fee_rate: BASE_MAKER_FEE,
min_size: 10 ** -(u.szDecimals ?? 0),
size_decimals: u.szDecimals ?? 0,
tick_size_usd: null,
funding_interval_seconds: 3600,
isolated_only: u.onlyIsolated === true,
logo_url: null,
asset_index: index,
};
})
.filter((m) => m.mark_price != null);
}
async function allMarkets() {
return memo('hl:markets', MARKETS_TTL_MS, async () =>
normalizeMarkets(await info('list markets', { type: 'metaAndAssetCtxs' })),
);
}
export async function listMarkets({ kind = null } = {}) {
if (kind && kind !== 'crypto') return [];
const rows = (await allMarkets()).filter((m) => m.status === 'active');
return rows
.map(({ asset_index: _i, ...m }) => m)
.sort((a, b) => (b.volume_24h_usd || 0) - (a.volume_24h_usd || 0));
}
async function marketRow(symbol) {
const sym = normalizeSymbol(symbol).toLowerCase();
const row = (await allMarkets()).find((m) => m.symbol.toLowerCase() === sym);
if (!row)
throw perpsError(
404,
'unknown_market',
`No Hyperliquid perps market "${symbol}". Call perps_markets for the list.`,
{ symbol },
);
return row;
}
export async function getMarket(symbol) {
const { asset_index: _i, ...market } = await marketRow(symbol);
return market;
}
/** Pure: Hyperliquid l2Book levels into the interface's book. */
export function normalizeL2(raw, depth = 20) {
const [bids, asks] = raw?.levels || [[], []];
const rows = (levels) => (levels || []).map((l) => [Number(l.px), Number(l.sz)]);
return {
...normalizeBook({ bids: rows(bids), asks: rows(asks), slot: raw?.time ?? null }, depth),
synthetic: false,
};
}
export async function getMarketData(symbol, { depth = 20, trades = 30, funding = 48 } = {}) {
const market = await getMarket(symbol);
const [book, fills, history] = await Promise.all([
info('read the order book', { type: 'l2Book', coin: market.symbol }),
trades > 0
? info('read recent trades', { type: 'recentTrades', coin: market.symbol })
: null,
funding > 0
? info('read funding history', {
type: 'fundingHistory',
coin: market.symbol,
startTime: Date.now() - funding * 3_600_000,
})
: null,
]);
return {
market,
book: normalizeL2(book, depth),
trades: (Array.isArray(fills) ? fills : []).slice(0, trades).map((t) => ({
price: Number(t.px),
size: Number(t.sz),
side: t.side === 'B' ? 'buy' : 'sell',
time: new Date(Number(t.time)).toISOString(),
signature: t.hash && !/^0x0+$/.test(t.hash) ? t.hash : null,
})),
funding: (Array.isArray(history) ? history : [])
.map((r) => ({
time: new Date(Number(r.time)).toISOString(),
rate_hourly_pct: round(Number(r.fundingRate) * 100, 8),
}))
.filter((r) => Number.isFinite(r.rate_hourly_pct)),
};
}
// ── account ──────────────────────────────────────────────────────────────────
/** Pure: clearinghouseState plus open orders into the interface's account shape. */
export function normalizeAccount(authority, state, openOrders = [], marks = new Map()) {
const positions = (state?.assetPositions || [])
.map(({ position: p }) => {
const signed = num(p?.szi) || 0;
if (signed === 0) return null;
const size = Math.abs(signed);
const mark =
marks.get(p.coin) ?? (num(p.positionValue) ? num(p.positionValue) / size : null);
const liq = num(p.liquidationPx);
return {
symbol: p.coin,
side: signed > 0 ? 'long' : 'short',
size,
signed_size: signed,
entry_price: num(p.entryPx),
mark_price: mark,
notional_usd: round(num(p.positionValue) ?? size * (mark || 0), 2),
unrealized_pnl_usd: round(num(p.unrealizedPnl), 4),
liquidation_price: liq && liq > 0 ? liq : null,
liquidation_distance_pct:
liq && liq > 0 && mark ? round((Math.abs(mark - liq) / mark) * 100, 2) : null,
initial_margin_usd: round(num(p.marginUsed), 4),
maintenance_margin_usd: null,
funding_accrued_usd: round(-(num(p.cumFunding?.sinceOpen) || 0), 4),
unsettled_funding_usd: 0,
take_profit_price: null,
stop_loss_price: null,
leverage: num(p.leverage?.value),
margin_mode: p.leverage?.type || null,
};
})
.filter(Boolean)
.sort((a, b) => b.notional_usd - a.notional_usd);
const orders = [];
const conditionals = [];
for (const o of openOrders) {
const side = o.side === 'B' ? 'buy' : 'sell';
if (o.isTrigger) {
const kind = /take profit/i.test(o.orderType || '') ? 'take_profit' : 'stop_loss';
conditionals.push({
id: String(o.oid),
symbol: o.coin,
kind,
trigger_price: num(o.triggerPx),
execution_price: num(o.limitPx),
side,
status: 'open',
cancellable: true,
});
} else {
orders.push({
id: String(o.oid),
symbol: o.coin,
side,
price: num(o.limitPx),
price_ticks: null,
size_remaining: num(o.sz),
reduce_only: o.reduceOnly === true,
type: 'limit',
status: 'open',
});
}
}
const cross = state?.crossMarginSummary || state?.marginSummary || {};
const equity = num(cross.accountValue) ?? 0;
const notional = num(cross.totalNtlPos) ?? positions.reduce((s, p) => s + p.notional_usd, 0);
const mm = num(state?.crossMaintenanceMarginUsed) ?? 0;
const im = num(cross.totalMarginUsed) ?? 0;
const nearest = positions.reduce(
(m, p) =>
p.liquidation_distance_pct != null ? Math.min(m, p.liquidation_distance_pct) : m,
Infinity,
);
return {
registered: true,
authority,
trader_account: authority,
collateral_usd: round(num(cross.totalRawUsd) ?? equity, 6),
equity_usd: round(equity, 6),
withdrawable_usd: round(num(state?.withdrawable) ?? 0, 6),
unrealized_pnl_usd: round(
positions.reduce((s, p) => s + (p.unrealized_pnl_usd || 0), 0),
6,
),
initial_margin_usd: round(im, 6),
maintenance_margin_usd: round(mm, 6),
funding_owed_usd: 0,
notional_usd: round(notional, 2),
account_leverage: equity > 0 ? round(notional / equity, 3) : 0,
risk_state: nearest < 5 ? 'at_risk' : 'healthy',
risk_tier: null,
positions,
orders,
conditionals,
};
}
export async function getAccount(address) {
if (!/^0x[0-9a-fA-F]{40}$/.test(String(address || ''))) {
throw perpsError(
400,
'invalid_venue_account',
'The Hyperliquid account must be a 0x address.',
);
}
const [state, open, markets] = await Promise.all([
info('read the account', { type: 'clearinghouseState', user: address }),
info('read open orders', { type: 'frontendOpenOrders', user: address }),
allMarkets(),
]);
return normalizeAccount(
address,
state,
Array.isArray(open) ? open : [],
new Map(markets.map((m) => [m.symbol, m.mark_price])),
);
}
/** The Hyperliquid account this agent trades: the owner's address, stored on the agent. */
export function accountRef({ meta }) {
const address = meta?.hyperliquid?.account;
if (!address) {
throw perpsError(
409,
'venue_account_missing',
'This agent has no Hyperliquid account linked. Link the owner address and approve the agent API wallet first (docs/perps.md, Hyperliquid setup).',
{ venue: id },
);
}
return address;
}
const unsupported = (what) => () => {
throw perpsError(
400,
'not_supported_on_venue',
`Hyperliquid through three.ws does not support ${what}. ${what === 'a deposit or withdrawal' ? 'Fund and withdraw on Hyperliquid itself; the agent API wallet cannot move funds.' : 'Use a market or limit order.'}`,
{ venue: id },
);
};
export const prepareAccount = unsupported('a trader account step');
export const submitPrepare = unsupported('a trader account step');
export const buildDeposit = unsupported('a deposit or withdrawal');
export const buildWithdraw = unsupported('a deposit or withdrawal');
export const buildConditional = unsupported('take-profit or stop-loss orders');
export const buildCancelConditional = unsupported('take-profit or stop-loss orders');
// ── quote ────────────────────────────────────────────────────────────────────
/**
* Pure: cross-margin liquidation price. Hyperliquid's documented formula:
* liq = price - side * available / size / (1 - side * mmr), where `available` is
* the account value left after the maintenance margin of every open position.
*/
export function liquidationPrice({ price, signedSize, equity, maintenanceTotal, mmr }) {
if (!signedSize || !(price > 0)) return null;
const side = signedSize > 0 ? 1 : -1;
const available = equity - maintenanceTotal;
const liq = price - (side * available) / Math.abs(signedSize) / (1 - side * mmr);
return liq > 0 ? liq : null;
}
async function feeRates(address) {
if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
return { taker: BASE_TAKER_FEE, maker: BASE_MAKER_FEE };
try {
const fees = await hlInfo({ type: 'userFees', user: address });
const taker = num(fees?.userCrossRate);
const maker = num(fees?.userAddRate);
if (taker != null && maker != null) return { taker, maker };
} catch {
// Fall back to the public base tier: a fee read never blocks a quote.
}
return { taker: BASE_TAKER_FEE, maker: BASE_MAKER_FEE };
}
export async function quoteOrder({
symbol,
side,
size,
type,
price = null,
reduceOnly = false,
slippageBps = 100,
account,
}) {
const row = await marketRow(symbol);
if (row.status !== 'active')
throw perpsError(
409,
'market_inactive',
`${row.symbol} is ${row.status} on Hyperliquid right now.`,
{ status: row.status },
);
if (!capabilities.order_types.includes(type)) {
throw perpsError(
400,
'order_type_unsupported',
`Hyperliquid takes ${capabilities.order_types.join(' and ')} orders here, not ${type}.`,
{ venue: id },
);
}
const sizeText = formatSize(size, row.size_decimals);
const sized = Number(sizeText);
if (!(sized > 0))
throw perpsError(
400,
'size_too_small',
`The smallest ${row.symbol} order is ${row.min_size} ${row.symbol}.`,
{ min_size: row.min_size },
);
const book = normalizeL2(
await info('read the order book', { type: 'l2Book', coin: row.symbol }),
100,
);
const isLong = side === 'long';
const mark = row.mark_price ?? book.mid;
const fees = await feeRates(account.authority);
let entry;
let feeRate;
let limitPrice;
let crossesBook = true;
let fill = null;
if (type === 'market') {
fill = estimateFill(isLong ? book.asks : book.bids, sized);
if (!fill.complete)
throw perpsError(
422,
'insufficient_liquidity',
`The visible ${row.symbol} book cannot fill ${sized} right now (only ${fill.filled}). Use a smaller size or a limit order.`,
{ fillable: fill.filled },
);
entry = fill.avg_price;
feeRate = fees.taker;
const slip = Math.max(0, Number(slippageBps) || 0) / 10_000;
limitPrice = Number(
formatPrice(
isLong ? fill.worst_price * (1 + slip) : fill.worst_price * (1 - slip),
row.size_decimals,
),
);
} else {
if (!(Number(price) > 0))
throw perpsError(400, 'price_required', 'A limit order needs a positive price.');
limitPrice = Number(formatPrice(price, row.size_decimals));
entry = limitPrice;
crossesBook = isLong
? book.best_ask != null && limitPrice >= book.best_ask
: book.best_bid != null && limitPrice <= book.best_bid;
feeRate = crossesBook ? fees.taker : fees.maker;
}
const notional = sized * entry;
const fee = notional * feeRate;
const existing = account.positions.find((p) => p.symbol === row.symbol) || null;
const delta = isLong ? sized : -sized;
if (reduceOnly) {
if (!existing || Math.sign(existing.signed_size) === Math.sign(delta)) {
throw perpsError(
409,
'nothing_to_reduce',
`A reduce-only ${side} needs an open ${isLong ? 'short' : 'long'} ${row.symbol} position to reduce.`,
);
}
if (sized > existing.size + 1e-12)
throw perpsError(
409,
'reduce_exceeds_position',
`Reduce-only size ${sized} is larger than the open position (${existing.size}).`,
{ position_size: existing.size },
);
}
const projected = projectPosition({
size: existing?.signed_size || 0,
entry: existing?.entry_price || 0,
delta,
price: entry,
});
const markRef = mark || entry;
const imBefore = existing ? (Math.abs(existing.signed_size) * markRef) / row.max_leverage : 0;
const imAfter = (Math.abs(projected.size) * markRef) / row.max_leverage;
const accountNotionalAfter =
account.notional_usd -
(existing ? existing.notional_usd : 0) +
Math.abs(projected.size) * markRef;
const equityAfter = account.equity_usd - fee + projected.realized_pnl;
const initialMarginAfter = account.initial_margin_usd - imBefore + imAfter;
const mmr = row.maintenance_margin_rate;
const otherMm = Math.max(
0,
account.maintenance_margin_usd -
(existing ? Math.abs(existing.signed_size) * markRef * mmr : 0),
);
const liq =
projected.size !== 0
? liquidationPrice({
price: markRef,
signedSize: projected.size,
equity: equityAfter,
maintenanceTotal: otherMm + Math.abs(projected.size) * markRef * mmr,
mmr,
})
: null;
return {
symbol: row.symbol,
side,
type,
reduce_only: reduceOnly === true,
size: sized,
size_text: sizeText,
mark_price: mark,
index_price: row.index_price,
entry_price: round(entry, 8),
limit_price: limitPrice,
crosses_book: crossesBook,
worst_book_price: fill?.worst_price ?? null,
slippage_bps: type === 'market' ? Number(slippageBps) : null,
notional_usd: round(notional, 4),
fee_rate: feeRate,
fee_usd: round(fee, 6),
market_max_leverage: row.max_leverage,
venue_params: { asset_index: row.asset_index, sz_decimals: row.size_decimals },
position_after: {
side: projected.size > 0 ? 'long' : projected.size < 0 ? 'short' : 'flat',
size: round(Math.abs(projected.size), 10),
entry_price: projected.size ? round(projected.entry, 8) : null,
notional_usd: round(Math.abs(projected.size) * markRef, 4),
realized_pnl_usd: round(projected.realized_pnl, 6),
},
liquidation_price: liq ? round(liq, 6) : null,
liquidation_distance_pct:
liq && markRef ? round((Math.abs(markRef - liq) / markRef) * 100, 3) : null,
margin_impact_usd: round(imAfter - imBefore, 6),
initial_margin_after_usd: round(initialMarginAfter, 6),
collateral_after_usd: round(account.collateral_usd - fee + projected.realized_pnl, 6),
equity_after_usd: round(equityAfter, 6),
free_collateral_after_usd: round(equityAfter - initialMarginAfter, 6),
account_notional_after_usd: round(accountNotionalAfter, 4),
account_leverage_after:
equityAfter > 0 ? round(accountNotionalAfter / equityAfter, 4) : null,
risk_increasing:
Math.abs(projected.size) > Math.abs(existing?.signed_size || 0) + 1e-12 ||
(existing &&
Math.sign(projected.size) !== Math.sign(existing.signed_size) &&
projected.size !== 0),
};
}
// ── actions ──────────────────────────────────────────────────────────────────
/** Pure: the exchange action for a quoted order. Key order is part of the signed bytes. */
export function buildOrderAction(quote) {
const { asset_index: assetIndex, sz_decimals: szDecimals } = quote.venue_params || {};
if (!Number.isInteger(assetIndex))
throw perpsError(
500,
'quote_incomplete',
'The quote carries no Hyperliquid asset index. Preview the order again.',
);
return {
type: 'order',
orders: [
{
a: assetIndex,
b: quote.side === 'long',
p: formatPrice(quote.limit_price, szDecimals),
s: quote.size_text,
r: quote.reduce_only === true,
t: { limit: { tif: quote.type === 'market' ? 'Ioc' : 'Gtc' } },
},
],
grouping: 'na',
};
}
export const buildOrder = async (_ref, quote) => buildOrderAction(quote);
/** Pure: the exchange action that cancels one resting order. */
export function buildCancelAction({ assetIndex, orderId }) {
return { type: 'cancel', cancels: [{ a: assetIndex, o: Number(orderId) }] };
}
export async function buildCancel(_ref, { symbol, orderId }) {
const row = await marketRow(symbol);
return buildCancelAction({ assetIndex: row.asset_index, orderId });
}
/**
* Pure: read Hyperliquid's answer to an order. Returns the fill or resting
* state, or throws the venue's own refusal reason.
*/
export function parseOrderResponse(res) {
if (res?.status !== 'ok') {
throw perpsError(
422,
'venue_rejected',
`Hyperliquid refused the request: ${typeof res?.response === 'string' ? res.response : JSON.stringify(res?.response ?? res).slice(0, 240)}`,
{ venue: id },
);
}
const status = res.response?.data?.statuses?.[0];
if (status?.error)
throw perpsError(422, 'venue_rejected', `Hyperliquid refused the order: ${status.error}`, {
venue: id,
});
if (status?.filled)
return {
state: 'filled',
order_id: String(status.filled.oid),
filled_size: Number(status.filled.totalSz),
avg_price: Number(status.filled.avgPx),
};
if (status?.resting) return { state: 'resting', order_id: String(status.resting.oid) };
return { state: 'accepted', order_id: null };
}
export async function ping() {
const t0 = Date.now();
await hlInfo({ type: 'meta' });
return { latency_ms: Date.now() - t0 };
}
/** API wallets the owner has approved on this account (address + name + expiry). */
export async function listApprovedApiWallets(account) {
const rows = await info('read approved API wallets', { type: 'extraAgents', user: account });
return (Array.isArray(rows) ? rows : []).map((r) => ({
address: String(r.address || '').toLowerCase(),
name: r.name ?? null,
valid_until: r.validUntil ?? null,
}));
}