Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (44 loc) · 2.45 KB

AGENTS.md

File metadata and controls

57 lines (44 loc) · 2.45 KB

AGENTS.md - Orderly CLI

CLI tool for Orderly Network trading. Keys stored in OS keychain — never exposed to AI context. The CLI handles signing internally and returns only results.

Run orderly --help for complete command reference. The CLI is self-documenting.

Critical Gotchas

  • --account is always required for authenticated commands. No default. Use orderly auth-list to get account IDs.
  • Hex account IDs must be quoted in shell: --account "0x5a6b..." (unquoted hex is parsed as float).
  • Symbol names must be uppercase: PERP_ETH_USDC, not PERP_ETH_usdc.
  • Default output is compact JSON. Use --csv for tabular data. API wrapper { success, data } is auto-unwrapped.
  • auth-export-key blocks AI agents: requires interactive TTY + typing "EXPORT".

Security Architecture

  • Layer 1 (Wallet): EIP-712 (EVM) or Ed25519 (Solana) — for account registration. Wallet keys in OS keychain.
  • Layer 2 (API): Ed25519 keypair for trading operations. Auto-generated by wallet-add-key. Stored in OS keychain, network-scoped as accountId:network.

Keychain backends: macOS Keychain, Windows Credential Manager, Linux libsecret/gnome-keyring.

Architecture

src/
├── index.ts              # CLI entry point (cac)
├── types.ts              # TypeScript interfaces
├── commands/             # One file per command group
│   ├── auth.ts, wallet.ts, account.ts, order.ts, algo.ts,
│   ├── positions.ts, market.ts, assets.ts, leverage.ts,
│   ├── trades.ts, funding.ts, settle.ts, faucet.ts
└── lib/
    ├── keychain.ts       # OS keychain (keytar)
    ├── crypto.ts         # Ed25519 key gen & signing (@noble/curves)
    ├── evm.ts            # EIP-712 signing (ethers)
    ├── solana.ts         # Ed25519 signing for Solana
    ├── config.ts         # ~/.orderly-cli/config.json
    ├── api.ts            # REST client with auto-signing
    └── account-select.ts # Account resolution

Build & Quality

yarn build          # esbuild bundle
yarn lint           # ESLint
yarn format         # Prettier
yarn typecheck      # tsc --noEmit
yarn test:run       # Vitest

Troubleshooting

  • Linux keychain: requires libsecret (sudo apt-get install libsecret-1-0 libsecret-1-dev)
  • 401: API key not registered. Run wallet-add-key.
  • 403: Signature invalid/expired. Check system clock.
  • Build errors: rm -rf dist && yarn build