cloudzombie/ship

Ship on Hyperliquid

What You Probably Got Wrong

You jumped straight to EVM contracts. Hyperliquid has two execution environments. Before writing any Solidity, ask: does this belong in HyperCore (perps, spot trading, orderbook) or HyperEVM (custom contract logic)? Most trading logic belongs in HyperCore via the API — not in a contract.

You over-engineer. Most Hyperliquid dApps need 0-2 HyperEVM contracts. Trading vaults? HyperCore handles positions natively. Token launch? HyperCore's HIP-1/HIP-2 bonding curve. Simple DEX swap? HyperSwap V2 already exists. Build on top, don't rebuild from scratch.

You forgot the two-API model. HyperCore uses POST /info (reads) and POST /exchange (signed writes) — not EVM RPC. HyperEVM uses standard EVM RPC at https://rpc.hyperliquid.xyz/evm. These are different systems. Know which one you're talking to.

You assumed Ethereum gas mechanics. HYPE is the gas token on HyperEVM, not ETH. Priority fees are burned, not given to validators. Nonces on HyperCore are NOT sequential — they're a rolling set of highest nonces per signer.

You thought testnet was optional. It's not. Chain ID 998 testnet at https://rpc.hyperliquid-testnet.xyz/evm. Always test there before mainnet. HyperCore testnet API: https://api.hyperliquid-testnet.xyz.

---

Phase 0 — Plan the Architecture

Do this BEFORE writing any code. One hour here saves ten hours of rewrites.

The HyperCore vs HyperEVM Decision

| Put it in HyperCore if... | Put it in HyperEVM if... | |---------------------------|--------------------------| | You're trading perps or spot | You need custom contract logic | | You're managing positions, margins | You need composability with ERC-20 tokens | | You want native orderbook access | You want to integrate with other HyperEVM contracts | | You're launching a HIP-1/HIP-2 token | You're building a yield vault, governance, escrow | | You want sub-second settlement | You need EVM event logs for indexing |

Most trading applications are primarily HyperCore. A vault that manages perp positions for users? HyperCore API + a thin HyperEVM interface for deposits/withdrawals. A token launchpad? HIP-1 bonding curve on HyperCore + a HyperEVM contract for the UI layer.

If you're building anything involving the native orderbook: HyperCore, not EVM contracts.

Fetch architecture/SKILL.md for the complete system model.

MVP Contract Count

| What you're building | Contracts | Pattern | |---------------------|-----------|---------| | Perp trading vault | 0-1 | HyperCore API + maybe deposit contract | | Token launch (HIP-1) | 0 | HyperCore native — no contract needed | | Spot DEX swap | 0 | HyperSwap V2 already deployed | | Custom yield strategy | 1 | HyperEVM vault + HyperCore API | | NFT collection | 1 | Standard ERC-721 on HyperEVM | | Governance / DAO | 1-3 | HyperEVM Governor + token + timelock | | Cross-protocol aggregator | 1-2 | HyperEVM router that calls HyperSwap + HyperCore |

If you need more than 3 contracts for an MVP, you're over-building.

The Onchain Litmus Test

Put it onchain (HyperEVM) if:

• Trustless custody — holding user funds in a contract
• Composability — other contracts need to call it
• Permanent commitments — votes, attestations, escrow
• Custom tokenomics — beyond what HIP-1/HIP-2 provides

Use HyperCore API directly if:

• Trading, position management, order placement
• Reading prices, funding rates, open interest
• Token launches via bonding curve
• Transferring between HyperCore and HyperEVM

State Transition Audit

For EVERY function in your contract or API action:

Action: ____________
Who initiates it? ____________
Why would they? ____________
What if nobody does? ____________
Does it need HYPE for gas? ____________
Is there a signing requirement? ____________

HyperCore actions require EIP-712 signatures. HyperEVM functions require gas in HYPE. Plan both.

---

dApp Archetype Templates

1. Perp Trading Interface / Vault (0-1 contracts)

Architecture: HyperCore API handles all the trading. HyperEVM contract (optional) for user deposits/withdrawals and accounting.

Components:

• HyperCore API calls via Python SDK or TypeScript SDK
• VaultDeposit.sol (optional) — ERC-20-like interface for the vault on HyperEVM
• HYPE bridge via 0x2222...2222 for moving funds between layers

Common mistakes:

• Trying to place orders from a Solidity contract — orders go through HyperCore API, not EVM
• Not handling HyperCore nonces correctly (they're rolling, not sequential)
• Forgetting to bridge HYPE from HyperCore to HyperEVM for gas

Fetch sequence: architecture/SKILL.md → api/SKILL.md → wallets/SKILL.md → security/SKILL.md

2. Token Launch (HIP-1 + HIP-2) (0 contracts)

Architecture: Deploy a HIP-1 spot token on HyperCore. Use HIP-2 for automated hyperliquidity. No EVM contract needed unless you want custom vesting or governance.

Components:

• HyperCore spot token creation via the API
• HIP-2 hyperliquidity seeding
• Bonding curve: x*y=k, graduates to full orderbook at threshold

Common mistakes:

• Trying to use ERC-20 instead of HIP-1 for a native token (you lose native DEX integration)
• Not seeding hyperliquidity — HIP-2 requires initial liquidity provision
• Confusing HyperCore spot decimals (6 typically) with HyperEVM decimals

Fetch sequence: standards/SKILL.md → building-blocks/SKILL.md → api/SKILL.md

3. Yield Vault (1-2 contracts on HyperEVM)

Architecture: HyperEVM vault accepts HYPE/USDC deposits. Vault manager uses HyperCore API to deploy into perp strategies. Users hold vault shares (ERC-20).

Contracts:

• HyperliquidVault.sol — ERC-4626-compatible vault accepting HYPE or USDC
• Optional: VaultStrategy.sol — operator logic for position management

Common mistakes:

• Not accounting for HYPE decimal difference (8 in HyperCore, 18 in HyperEVM after bridging)
• Missing reentrancy protection on withdrawal functions
• No slippage protection on HyperCore position entry/exit

Fetch sequence: standards/SKILL.md → building-blocks/SKILL.md → security/SKILL.md → testing/SKILL.md

4. HyperSwap Integration / DEX Aggregator (0-1 contracts)

Architecture: Route swaps through HyperSwap V2 (already deployed). Optionally wrap in a contract for custom fee logic or multi-hop routing.

Components:

• HyperSwap V2 Router (deployed, see addresses/SKILL.md)
• Optional: Aggregator.sol — if you need custom routing logic

Common mistakes:

• Deploying your own AMM when HyperSwap V2 already has liquidity
• Not using the correct Router address (see addresses/SKILL.md)
• Ignoring slippage on HyperSwap swaps (use amountOutMinimum)

Fetch sequence: building-blocks/SKILL.md → addresses/SKILL.md → security/SKILL.md

5. AI Agent Trading Bot (0 contracts)

Architecture: Pure HyperCore API. Python SDK or TypeScript SDK. Agent wallet with approved subaccount keys.

Components:

• Python or TypeScript agent using official SDK
• API wallet pattern (agent key approved by main wallet)
• No contracts unless managing user funds

Common mistakes:

• Using main wallet private key in the bot (use API wallet pattern)
• Not handling rate limits (429) with exponential backoff
• Hardcoding nonces (let the SDK manage them)

Fetch sequence: api/SKILL.md → wallets/SKILL.md → concepts/SKILL.md → tools/SKILL.md

---

Phase 1 — Build

Fetch: standards/SKILL.md, building-blocks/SKILL.md, addresses/SKILL.md, security/SKILL.md, api/SKILL.md

For HyperEVM contracts:

• Use OpenZeppelin base contracts — don't reinvent ERC-20, ERC-721, AccessControl
• HYPE has 18 decimals on HyperEVM (same as ETH). USDC has 6.
• Use verified addresses from addresses/SKILL.md — never fabricate addresses
• Emit events for every state change
• Run through the security checklist before Phase 2

For HyperCore API integration:

• Use the official SDK (Python: hyperliquid-dex, TypeScript: @nktkas/hyperliquid)
• Always sign with EIP-712 for exchange actions
• Use agent wallets for automated bots — never expose main wallet keys
• Handle nonce management carefully — see concepts/SKILL.md

---

Phase 2 — Test

Fetch: testing/SKILL.md

HyperEVM testing:

# Fork HyperEVM mainnet for local testing
anvil --fork-url https://rpc.hyperliquid.xyz/evm

# Or test against actual testnet
# Chain ID: 998, RPC: https://rpc.hyperliquid-testnet.xyz/evm

HyperCore API testing:

• Use testnet API: https://api.hyperliquid-testnet.xyz
• Get testnet HYPE from the faucet
• Test all order types, cancellations, nonce edge cases

---

Phase 3 — Build Frontend

Fetch: orchestration/SKILL.md, frontend-ux/SKILL.md, tools/SKILL.md

wagmi/viem chain config:

import { defineChain } from 'viem';

export const hyperliquid = defineChain({
  id: 999,
  name: 'HyperEVM',
  nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://rpc.hyperliquid.xyz/evm'] },
  },
  blockExplorers: {
    default: { name: 'HyperEVM Explorer', url: 'https://explorer.hyperliquid.xyz' },
  },
});

Show loading states on every async operation. HyperEVM blocks are ~1s but HyperCore actions are near-instant (sub-second). Differentiate in the UI.

---

Phase 4 — Ship to Production

Fetch: wallets/SKILL.md, frontend-playbook/SKILL.md, gas/SKILL.md

Contract Deployment

1. Deploy to HyperEVM testnet (chain ID 998) first
2. Verify contracts on HyperEVM block explorer
3. Transfer ownership to a multisig — never leave single EOA as owner in production
4. Deploy to mainnet (chain ID 999)

HyperCore Integration

1. Switch from testnet API to mainnet API (api.hyperliquid.xyz)
2. Fund the agent wallet with enough HYPE for gas
3. Test small orders first before full automation

Pre-Ship QA

Run the QA checklist. Fetch qa/SKILL.md and give it to a separate reviewer agent.

---

Anti-Patterns

Reinventing HyperCore. Don't write an orderbook in Solidity when HyperCore has a native one processing 100k orders/sec.

Wrong layer. Trading logic in EVM contracts. Settlement logic in API calls that should be onchain. Know which layer does what.

Nonce carelessness. HyperCore nonces are rolling-set, not sequential. Using an old nonce or collision causes rejected orders. Let the SDK manage nonces.

Hardcoded testnet. Deploying to testnet then forgetting to switch to mainnet for production.

Admin key in production. Using a single EOA as contract owner in production. Use a multisig.

---

Quick-Start Checklist

• [ ] Decide: HyperCore API vs HyperEVM vs both?
• [ ] Plan the architecture — what layer handles what?
• [ ] Count your contracts (aim for 0-2 for MVP)
• [ ] Identify all HyperCore API calls needed
• [ ] Write contracts using OpenZeppelin base contracts
• [ ] Test on HyperEVM testnet (chain ID 998) + HyperCore testnet API
• [ ] Deploy HyperEVM contracts, verify on explorer
• [ ] Deploy frontend
• [ ] Run pre-ship QA with a separate reviewer

---

Skill Routing Table

| Phase | What you're doing | Skills to fetch | |-------|-------------------|-----------------| | Plan | Architecture | ship/ (this), architecture/, concepts/, why/ | | Contracts | Writing Solidity | standards/, building-blocks/, addresses/, security/ | | API Integration | HyperCore API | api/, wallets/, concepts/ | | Test | Testing | testing/ | | Frontend | Building UI | orchestration/, frontend-ux/, tools/ | | Production | Deploy, QA | wallets/, frontend-playbook/, qa/, indexing/ |