elizaos--eliza/plugins/plugin-hyperliquid/README.md

@elizaos/plugin-hyperliquid

Adds native Hyperliquid perpetual-market integration to elizaOS agents. Eliza agents can query market listings, credential readiness, account positions, and open orders through both conversational actions and HTTP routes. Order placement is disabled by design — the plugin is read-only.

Capabilities

• Market discovery — list all Hyperliquid perpetual markets with max leverage, size decimals, and active/delisted status.
• Account positions — read open perp positions for a configured EVM address (size, entry price, unrealized PnL, leverage, liquidation price).
• Open orders — read working limit orders for a configured account.
• Credential status — inspect which credential mode is active (managed_vault, local_key, or none) and whether account reads are available.
• React UI view — dashboard GUI view shipped in the plugin bundle and surfaced as an agent app tab.

Actions

PERPETUAL_MARKET

Conversational action that routes to the Hyperliquid provider. Recognized when the message contains Hyperliquid-related keywords (in English and several other languages) or when a finance, crypto, trading, or payments context is active.

Parameters:

Parameter	Values	Description
action	read, place_order	Operation type. place_order returns a disabled-execution notice.
kind	status, markets, market, positions, funding	Sub-kind for action=read.
coin	e.g. BTC, ETH	Asset symbol for kind=market.
target	hyperliquid (default)	Provider selector; only Hyperliquid is registered today.

Examples:

• "What is the Hyperliquid trading status?" → action=read kind=status
• "Show me Hyperliquid perp markets" → action=read kind=markets
• "What are my Hyperliquid positions?" → action=read kind=positions
• "Tell me about the BTC perp on Hyperliquid" → action=read kind=market coin=BTC

API routes

All routes are mounted under /api/hyperliquid/. Public market reads require no credentials. Account reads require an EVM address to be configured.

Method	Path	Description
GET	/api/hyperliquid/status	Credential and readiness status
GET	/api/hyperliquid/markets	All perpetual markets
GET	/api/hyperliquid/funding	Current funding rates and asset contexts
GET	/api/hyperliquid/positions	Account perp positions
GET	/api/hyperliquid/orders	Open orders
POST	/api/hyperliquid/orders/open	Disabled — returns 501
POST	/api/hyperliquid/orders/close	Disabled — returns 501
POST	/api/hyperliquid/leverage	Disabled — returns 501
POST	/api/hyperliquid/margin	Disabled — returns 501
POST	/api/hyperliquid/bridge	Disabled — returns 501
POST	/api/hyperliquid/tpsl	Disabled — returns 501

Configuration

No env vars are required for public market reads. To enable account-specific reads, configure one of:

Env var	Description
HYPERLIQUID_ACCOUNT_ADDRESS or HL_ACCOUNT_ADDRESS	EVM address for positions/orders reads. Must be 0x-prefixed 40-char hex.
STEWARD_EVM_ADDRESS or ELIZA_MANAGED_EVM_ADDRESS	Managed-vault EVM address (takes priority over the explicit env account).

Optional signing credentials (reported in status only; this app keeps order execution disabled by design):

Env var	Description
EVM_PRIVATE_KEY, HYPERLIQUID_PRIVATE_KEY, or HL_PRIVATE_KEY	Local signer private key.
HYPERLIQUID_AGENT_KEY or HL_AGENT_KEY	Hyperliquid API-wallet delegation key.

Enabling the plugin

Load @elizaos/plugin-hyperliquid in your agent character config:

{
  "plugins": ["@elizaos/plugin-hyperliquid"]
}

Or register it programmatically:

import { hyperliquidPlugin } from "@elizaos/plugin-hyperliquid";

const runtime = new AgentRuntime({
  plugins: [hyperliquidPlugin],
  // ...
});

The plugin also self-registers as an elizaOS overlay app and route-plugin loader when imported, so it appears as a tab in the agent dashboard.

Notes

• Order placement (POST routes) is intentionally disabled in this version. The place_order action op reports the blocked-execution reason rather than submitting any transaction.
• Funding-rate reads (kind=funding) use Hyperliquid's live metaAndAssetCtxs Info API response.
• Market data is fetched from https://api.hyperliquid.xyz/info (the public Hyperliquid Info API). No API key is required.