Official AI agent skills, TypeScript SDK and MCP server (117 tools) for GDEX (gdex.pro), Gemach DAO's multi-chain trading terminal: Solana and EVM spot, Hyperliquid perps, copy trading
GDEX_API_KEY, GDEX_API_URL
Zuletzt geprüft
2026-10-28
Sterne
4
Tools
—
Uptime
—
AI Agent Skill for GDEX Pro — the self-custody trading terminal by Gemach
Cross-chain spot · HyperLiquid perps · Copy trading · Portfolio · Token discovery · Managed custody
Why agents use GDEX
GDEX is the trading surface. This skill is how AI agents (Claude, Cursor, Codex, and 40+ others) install and trade on it — spot, perps, copy-trade, and bridge — without building their own exchange stack.
Each skill's description tells the agent when to load it. No API key setup required for trading skills (shared keys are built in).
Risk & Market Data Skills
Deterministic data feeds and events for risk and research. Each ships a standard-library Python script that
prints NDJSON: no API key, no install, and every number comes from the script, not a model.
Scored, time-stamped HyperLiquid anomaly events (oracle divergence, funding extremity, liquidity shock) against per-market learned baselines, plus a coverage record per run. Backtest
gdex-token-risk
GDEX token screen on 12 chains: price, liquidity, volume, honeypot, taxes, LP lock, holder concentration (missing security data is never "safe")
gvault
GVault (GMACL, Enzyme on Ethereum): NAV, share price, holdings, cumulative and annualised return
harness/ runs these skills with Claude on your own Anthropic API key.
export produces every feed with no model; ask answers questions with an agent that can only
cite figures that skill scripts printed. Every script run is logged with a sha256 of its output.
🔌 MCP Server
The GDEX MCP server exposes 154 tools — full trading execution + SDK documentation — as Model Context Protocol tools. Any MCP-compatible AI agent can trade autonomously.
Source code: the server is implemented in this repository, in mcp-server/. The entry point is mcp-server/src/index.ts and the tool handlers are in mcp-server/src/tools/. The npm package @gemachdao/gdex-mcp-server is built from that directory by the release workflow. See mcp-server/README.md to run it from source or with the repo's Dockerfile.
init merges into an existing config: other MCP servers and settings are kept, the previous file is saved as <file>.bak, and rerunning is a no-op. If a different gdex-mcp-server entry is already there it is shown and left alone unless you pass --force; a config it can't parse is never modified.
Agents should start with gdex_status, connect once with gdex_connect, then gdex_preview_trade → gdex_execute_trade (user-approved, or within the delegated policy in ~/.gdex/policies/<accountRef>.json) → gdex_operation, and manage exits with gdex_positions / gdex_manage_position. Every tool carries read/write annotations. See the gdex-agent-trading skill.
Connect an account (no secrets in chat)
Ask your agent to run gdex_connect with a key file on your machine, e.g. gdex_connect { keyFile: "~/my-gdex-wallet.json" } (JSON with privateKey), or gdex_connect { create: true } for a new wallet. The server signs in, stores the keys under ~/.gdex/accounts (mode 0600) and returns an accountRef. Pass accountRef to any trading tool instead of sessionPrivateKey/privateKey. Never paste a private key or seed phrase into the chat. gdex_accounts lists connected accounts; gdex_disconnect forgets one.
One USDC balance across 7 chains; buy with USDC or native with automatic cross-chain funding and gas, live funding progress, sell to USDC, convert gas to USDC, bridge USDC
Read a file a skill ships with (e.g. scripts/token_risk.py)
📦 SDK Installation
npm install github:GemachDAO/gdex-skill
Installs the SDK straight from GitHub (it builds on install). Imports stay
from '@gemachdao/gdex-skill'. Pin a release with
npm install github:GemachDAO/gdex-skill#v4.1.1.
The install script displays a quick-start banner in your terminal. Optional peer dependencies for wallet signing (only needed for user-specific wallet auth):
const skill = new GdexSkill({
apiUrl: 'https://trade-api.gemach.io/v1', // Backend (default)
timeout: 30000, // Request timeout ms
maxRetries: 3, // Retry attempts on 429/503
debug: false, // Log every request
});
The SDK does not read environment variables directly. If you choose to use env vars,
read them in your application (for example via process.env) and pass their values into
the GdexSkill constructor as shown above.
Recommended environment variables for your own app:
Env Variable
Description
Default
GDEX_API_URL
Backend base URL to pass as apiUrl
https://trade-api.gemach.io/v1
GDEX_API_KEY
API key for AES encryption in managed-custody flow
—
GDEX_TIMEOUT
Request timeout (ms) to pass as timeout
30000
GDEX_MAX_RETRIES
Retry attempts to pass as maxRetries
3
GDEX_DEBUG
Enable debug logging to pass as debug
false
GDEX_CONTROL_WALLET
Control wallet address (userId) for managed custody
—
GDEX_SESSION_PRIVATE
Session private key (hex, 0x-prefixed) for managed custody
—
GDEX_MANAGED_CHAIN_ID
Chain ID for managed trades (622112261=Solana, 42161=Arbitrum for perps)
622112261
CONFIRM_LIVE_TRADE
Set to YES to submit real trades
—
🔒 Managed-Custody Trading
All trading on GDEX goes through server-side managed wallets. Your control wallet (EVM or Solana) is only used to authenticate (sign-in) — actual on-chain execution is handled by GDEX backend trade workers.
How It Works
Generate a session keypair — secp256k1 key used to sign trades after auth
Sign-in — control wallet signs a message, encrypted as computedData → POST /v1/sign_in
Resolve user — GET /v1/user with encrypted session key to see managed wallets
Trade — ABI-encode trade data, sign with session key, encrypt as computedData → POST /v1/purchase_v2 or /v1/sell_v2
Poll status — GET /v1/trade-status/:requestId until completed/failed
Encryption
All authenticated payloads use AES-256-CBC with a deterministic key/IV derived from the API key (no random IV):
v = raw recovery parameter (00 or 01), NOT EIP-155 (1b/1c)
HL perp signatures use the same algorithm but with HL-specific action prefixes (hl_deposit, hl_withdraw, hl_create_order, etc.) and different ABI schemas. See the HL Managed-Custody Reference section.
Sign-in signatures use EIP-191 personal_sign with the control wallet — this is the ONLY operation that uses EIP-191. All post-sign-in operations use raw keccak256.
Nonce Generation
Nonces are client-generated (not fetched from the server):
Copy trade payloads are ABI-encoded (create: 12 fields, update: 16 fields, chainId is uint256), signed and encrypted inside these GdexSkill methods; the encoders are not exported
buildEncryptedGdexPayload({...})
Encrypt JSON {userId, data, signature} for computedData
encryptGdexComputedData(plaintext, apiKey)
AES-256-CBC encrypt UTF-8 plaintext
encryptGdexHexData(hexData, apiKey)
AES-256-CBC encrypt raw hex-decoded bytes
decryptGdexComputedData(cipherHex, apiKey)
AES-256-CBC decrypt to UTF-8 plaintext
deriveGdexAesMaterial(apiKey)
Get raw AES key/IV from API key
Verify Managed Flow (offline)
npm run verify:managed
This generates all payloads (session keypair, sign-in, user lookup, trade), validates encrypt/decrypt roundtrips, and prints the full execution plan — without making any live API calls.
Critical: HyperLiquid deposits/withdrawals/orders use a different crypto flow than spot trades. See the HL Managed-Custody Reference section below for exact specifications.
Every perp write takes the managed-custody credentials { apiKey, walletAddress, sessionPrivateKey },
where walletAddress is the control wallet that signed in (MCP: pass accountRef from gdex_connect).
hlCreateOrder(params) — open (or add to) a position
Parameter
Type
Default
Description
coin
string
Asset symbol (e.g., 'BTC', 'ETH', builder markets as 'xyz:NVDA')
isLong
boolean
true long, false short
price
string
Limit price; for market orders the mark price ('0' resolves to mark)
size
string
Size in contracts (coin units), not USD. Min order value $11
// Deposit USDC to HyperLiquid from Arbitrum (human-readable amount, converted internally; min 10 USDC)
await skill.perpDeposit({
tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC on Arbitrum
amount: '10',
chainId: 42161,
apiKey, walletAddress, sessionPrivateKey,
});
await skill.perpWithdraw({ amount: '5', apiKey, walletAddress, sessionPrivateKey });
// Positions live on the managed EVM wallet
const positions = await skill.getPerpPositions({ walletAddress: managedEvmAddress });
// Each: { coin, side, size, entryPrice, markPrice, leverage, unrealizedPnl, liquidationPrice }
HL Deposit notes: Amount is in human-readable USDC (e.g., '10' for 10 USDC). The SDK automatically converts to smallest unit (6 decimals). Minimum deposit is 10 USDC. Your managed wallet must have the deposit amount + 1% fee buffer in USDC on Arbitrum. After the on-chain tx confirms, HyperLiquid takes ~10 minutes to credit the deposit.
Direct HyperLiquid Execution (via @gdexsdk/hyper-liquid-trader)
For direct trading on HyperLiquid L1 without managed custody — use your own private key:
const ids = { apiKey: GDEX_API_KEY_PRIMARY, userId: controlWalletAddress, sessionPrivateKey, copyTradeId: '<64-char-hex-id>' };
await skill.updateCopyTradeSettings({ ...ids, lossPercent: '40' }); // never deletes or pauses
await skill.pauseCopyTrade(ids); // isActive=false; no-op if already paused
await skill.resumeCopyTrade(ids); // isActive=true; no-op if already active
await skill.deleteCopyTrade(ids); // permanent
Each reads the current config from /copy_trade/list first, because the backend
rewrites every field on update and isChangeStatus is a relative toggle
(isActive = !existing.isActive). Deleting removes the configuration only:
positions it opened are not sold and their TP/SL limit orders are not
cancelled. While paused the copier mirrors neither buys nor sells.
Copy Trade ABI Reference
Typed exactly as the backend decodes them (src/shared/parser/evm/decoder.ts):
SDK versions up to 4.12 encoded every field as a string; the backend then decoded isDelete=true, so every update deleted. Nonce is auto-generated by the SDK.
HL Perp Copy Trading
Completely separate from Solana copy trading above. This copies perpetual futures positions (long/short) on HyperLiquid. Sign-in uses chainId: 1. All ABI fields are strings.
Configs written by SDK <= 4.12 (string-encoded ABI) hold copyMode 416/480 and oppositeCopy: true; repair them with updateHlCopyTradeSettings and explicit values. isChangeStatus toggles isActive; only isDelete deletes.
Portfolio
// Portfolio on one chain (managed-account read: also pass the session, see gdex-portfolio)
const portfolio = await skill.getPortfolio({ walletAddress: '0x...', chain: ChainId.BASE });
// { totalValueUsd, balances, perpPositions?, realizedPnl, unrealizedPnl }
// Chain-specific balances
const balances = await skill.getBalances({ walletAddress: '0x...', chain: ChainId.ETHEREUM });
// Paginated trade history
const history = await skill.getTradeHistory({
walletAddress: '0x...', chain: ChainId.BASE, page: 1, limit: 20,
startTime: 1700000000, endTime: 1700086400,
});
Native-token bridging (amounts in raw units: wei / lamports). For USDC see the Unified USDC Wallet.
// Get quote first (no auth)
const quote = await skill.estimateBridge({
fromChainId: ChainId.ETHEREUM,
toChainId: ChainId.BASE,
amount: '100000000000000000', // 0.1 ETH in wei
});
console.log('Output:', quote.estimateAmount, '— ETA (s):', quote.minEstimateTime, '-', quote.maxEstimateTime);
// Execute bridge (managed custody; sign in with chainId 1)
const result = await skill.requestBridge({
fromChainId: ChainId.ETHEREUM,
toChainId: ChainId.BASE,
amount: '100000000000000000',
userId: controlAddress,
sessionPrivateKey,
apiKey,
});
console.log(result.isSuccess, result.hash);
Wallet Info
// Managed-account read: control walletAddress plus the session (sessionPrivateKey + apiKey, or data)
const info = await skill.getWalletInfo({ walletAddress: controlWalletAddress, sessionPrivateKey, apiKey, chain: 'solana' });
// { address, nativeBalance, nativeSymbol, totalValueUsd, tokenCount }
Wallet Generation
🔓 No authentication required. Keys are generated locally and never transmitted.
When a user doesn't have a wallet yet, generate an EVM control wallet for them. Then use the managed-custody sign-in flow to authenticate, and the Gbot backend automatically provisions a full trading wallet — including a Solana address and other chain-specific keys — server-side. No separate Solana wallet generation is needed.
generateEvmWallet() — your control wallet
Generates a new EVM-compatible wallet (Ethereum, Base, Arbitrum, BSC, etc.) using ethers.Wallet.createRandom().
import {
GdexSkill,
generateEvmWallet,
generateGdexSessionKeyPair,
buildGdexSignInMessage,
GDEX_API_KEY_PRIMARY,
} from '@gemachdao/gdex-skill';
// Step 1: generate your EVM control wallet (one-time setup)
const wallet = generateEvmWallet();
console.log(wallet.address); // '0xAbCd...' (checksummed) — safe to share
// ⚠️ Store wallet.privateKey and wallet.mnemonic securely
// Step 2: generate a session keypair for managed-custody trading
const { sessionPrivateKey, sessionKey } = generateGdexSessionKeyPair();
// Step 3: build the sign-in message and sign with your control wallet
const message = buildGdexSignInMessage(wallet.address, String(Date.now()), sessionKey);
// Sign with: new ethers.Wallet(wallet.privateKey).signMessage(message)
// Step 4: submit sign_in computedData (see Managed-Custody Trading section above)
// The backend provisions Solana + all other trading wallets server-side
🌐 Supported Chains
Chain
ChainId
Native Token
DEXes
Ethereum
1
ETH
Uniswap V2/V3, Odos
Optimism
10
ETH
Uniswap V3, Odos
BNB Smart Chain
56
BNB
PancakeSwap, Odos
Sonic
146
S
—
Fraxtal
252
frxETH
Uniswap V3
Nibiru
6900
NIBI
—
Base
8453
ETH
Uniswap V3, Odos, Arcadia
Arbitrum One
42161
ETH
Uniswap V3, Odos
Berachain
80094
BERA
—
Solana
622112261
SOL
Raydium, Raydium V2, Orca
Sui
1313131213
SUI
Cetus, Bluefin
HyperLiquid
perps only
USDC
Native perp engine
The ChainId enum is wider than this table. It also defines Avalanche (43114), Polygon
(137), zkSync Era (324), Linea (59144), Blast (81457) and Scroll (534352). The backend's
supportedChainIds does not include them, so calls against those ids will not route. Trade
only the chains listed above.
All 103 tests run with mocked HTTP — no real API key or network connection required:
npm test # run all 103 tests
npm run test:coverage # with coverage report
npm run verify # offline SDK smoke-test (20 checks)
npm run verify:managed # managed-custody payload validation (dry-run)
Test suites:
tests/client/auth.test.ts — API key auth, EVM/Solana wallet signing
tests/actions/portfolio.test.ts — balances, history, wallet info
tests/actions/tokenInfo.test.ts — trending, OHLCV, token details, top traders
tests/utils/walletGeneration.test.ts — EVM control wallet generation (offline)
tests/utils/gdexManagedCrypto.test.ts — managed-custody crypto helpers (AES, signing, ABI encoding)
🏗 Architecture
AI Agent (Claude Code / Cursor / Codex / ...)
│
│ npx skills add GemachDAO/gdex-skill
│ ──────────────────────────────────
│ SKILL.md → agent skill directory
│
▼
@gemachdao/gdex-skill (this package)
│ TypeScript methods with full type safety
│ @gdexsdk/hyper-liquid-trader for HyperLiquid L1 queries & direct execution
│ Managed-custody: AES-256-CBC encryption + secp256k1 session signing
│ computedData payloads for all trade operations
│ Auto-retry with exponential backoff
│
│ Control Wallet (EVM / Solana)
│ └─ signs once for /v1/sign_in → session keypair
│
▼
Gbot Backend API (https://trade-api.gemach.io/v1)
│ Decrypt computedData → verify signature → resolve nonce (gRPC)
│ NATS JetStream trade queue
│ Server-side managed wallets (custody)
│ DEX aggregation engine
▼
Blockchains (Solana · Sui · Ethereum · Base · Arbitrum · …)
HL Managed-Custody Reference
HyperLiquid perp operations use a distinct crypto pipeline from spot trades. Getting any detail wrong produces a 400 Unauthorized (code 103) error. This section documents the exact specification.
HL Deposit Flow
The backend custodially executes the on-chain deposit: it loads the user's server-side private key, constructs an Arbitrum transaction, and sends USDC to the HyperLiquid bridge receiver. The agent only provides an authorization signature.
Agent SDK Backend
──────── ───────
1. ABI-encode deposit params ──► 2. AES-decrypt computedData
(uint64 chainId, address, 3. ABI-decode data
uint256 amount, string nonce) 4. Verify chainId == 42161
2. Sign with session key ──► 5. Verify signature vs stored sessionKey
3. AES-encrypt as computedData ──► 6. Validate token, balance, min deposit
4. POST /v1/hl/deposit 7. Execute ERC-20 transfer on Arbitrum
WARNING: The hl_deposit chainId uses uint64, NOT uint256. This is the single most common cause of "Unauthorized" errors. The backend re-encodes with uint64 for signature verification — if you encode with uint256, the hex differs, signature recovery fails, and you get code 103.
HL Signature Format
All HL write operations sign with the session private key (from sign-in), NOT the control wallet key:
// Message format (no EIP-191 prefix):
const msg = `${action}-${userId.toLowerCase()}-${dataHex}`;
// e.g.: "hl_deposit-0x53d029a6...-00000000000000000000000000000000000000000000000000000000..."
const digest = keccak256(toUtf8Bytes(msg));
const sig = new SigningKey(sessionPrivateKey).sign(digest);
// Output: r(64hex) + s(64hex) + v(2hex) = 130 chars, no 0x prefix
// v = raw recovery parameter (00 or 01), NOT EIP-155 (1b/1c)
HL Deposit Constraints
Constraint
Value
Chain
Arbitrum only (chainId 42161)
Token
USDC only (0xaf88d065e77c8cC2239327C5EDb3A432268e5831)
Amount
In smallest unit (6 decimals): 10 USDC = 10000000
Min deposit
10 USDC
Fee buffer
Balance must cover amount × 1.01
Delivery time
~10 minutes after Arbitrum tx confirms
Bridge receiver
0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7
userId
Control wallet address (from sign-in), NOT managed wallet
HL Error Codes
Code
Error
Cause
101
Missing params
computedData not in request body
102
Invalid chainId
chainId is not 42161
102
Invalid params
Nonce already used, or token not supported
103
Unauthorized
Signature verification failed — check ABI types (uint64!), userId, and that you're signing with the session key registered during sign-in
—
Insufficient balance
Managed wallet doesn't have enough USDC + fee on Arbitrum
—
Too low amount
Amount < 10 USDC
HTTP Headers (Required)
The backend sits behind Cloudflare. Requests MUST include browser-like headers:
{
'Content-Type': 'application/json',
'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
'Accept': 'application/json',
'Accept-Language': 'en-US,en;q=0.9',
'Accept-Encoding': 'gzip, deflate, br',
'Connection': 'keep-alive',
'Authorization': 'Bearer <apiKey>', // NOT X-API-Key
}
WARNING: Using a non-browser User-Agent (e.g., axios/1.x or any string containing bot identifiers) will result in Cloudflare 403 "Access denied". The SDK handles this automatically.
Complete HL Deposit Example
import {
GdexSkill,
GDEX_API_KEY_PRIMARY,
generateGdexSessionKeyPair,
buildGdexSignInMessage,
buildGdexSignInComputedData,
buildHlComputedData,
} from '@gemachdao/gdex-skill';
import { ethers } from 'ethers';
const apiKey = GDEX_API_KEY_PRIMARY;
const skill = new GdexSkill();
skill.loginWithApiKey(apiKey);
// 1. Generate session keypair
const { sessionPrivateKey, sessionKey } = generateGdexSessionKeyPair();
// 2. Sign in (control wallet signs the Terms message)
const controlWallet = new ethers.Wallet('0xYourPrivateKey');
const nonce = String(Date.now());
const message = buildGdexSignInMessage(controlWallet.address, nonce, sessionKey);
const signature = await controlWallet.signMessage(message);
const signInPayload = buildGdexSignInComputedData({
apiKey, userId: controlWallet.address, sessionKey, nonce,
signature: signature.replace(/^0x/, ''),
});
await skill.signInWithComputedData({
computedData: signInPayload.computedData, chainId: 42161,
});
// 3. Deposit USDC (amount in smallest unit, uint64 chainId is handled by SDK)
const computedData = buildHlComputedData({
action: 'hl_deposit',
apiKey,
walletAddress: controlWallet.address, // userId = control wallet
sessionPrivateKey,
actionParams: {
chainId: 42161,
tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
amount: '10000000', // 10 USDC in smallest unit (6 decimals)
},
});
const result = await skill.client.post('/v1/hl/deposit', { computedData });
// { hash: '0x...', isSuccess: true, amount: '10000000', message: 'Deposit successfully...' }
// Wait ~10 minutes for HyperLiquid to credit the deposit
Official AI agent skills, TypeScript SDK and MCP server (117 tools) for GDEX (gdex.pro), Gemach DAO's multi-chain trading terminal: Solana and EVM spot, Hyperliquid perps, copy trading
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Gdex Skill?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Gdex Skill einen API-Schlüssel?
Der Herausgeber nennt diese Umgebungsvariablen: GDEX_API_KEY, GDEX_API_URL.
Welchen Transport verwendet Gdex Skill?
Gdex Skill läuft lokal über stdio.
Wann wurde Gdex Skill zuletzt geprüft?
Zuletzt geprüft: 2026-10-28. Official AI agent skills, TypeScript SDK and MCP server (117 tools) for GDEX (gdex.pro), Gemach DAO's multi-chain trading terminal: Solana and EVM spot, Hyperliquid perps, copy trading