> For the complete documentation index, see [llms.txt](https://docs.gemach.io/gemach-dao/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gemach.io/gemach-dao/products/agent-skills/gdex-trading-skills.md).

# GDEX Trading Skills

The trading skills give any agent full-stack DeFi capability through the `@gdexsdk/gdex-skill` package — spot swaps, HyperLiquid perpetual futures, limit orders, copy trading, bridging, portfolio analytics, and token discovery. Every example below uses the actual SDK method names and parameters from [`GemachDAO/gdex-skill`](https://github.com/GemachDAO/gdex-skill).

## Supported Chains

| Chain           | ChainId      | Native Token |
| --------------- | ------------ | ------------ |
| Ethereum        | `1`          | ETH          |
| Optimism        | `10`         | ETH          |
| BNB Smart Chain | `56`         | BNB          |
| Sonic           | `146`        | S            |
| Fraxtal         | `252`        | frxETH       |
| Nibiru          | `6900`       | NIBI         |
| Base            | `8453`       | ETH          |
| Arbitrum One    | `42161`      | ETH          |
| Berachain       | `80094`      | BERA         |
| Solana          | `622112261`  | SOL          |
| Sui             | `1313131213` | SUI          |
| HyperLiquid     | perps only   | USDC         |

{% hint style="warning" %}
The Solana numeric chainId is **`622112261`** (`ChainId.SOLANA`), **not** `900`. Using `900` returns the EVM managed wallet with a `null` balance.
{% endhint %}

## Authentication

### Shared API keys (recommended for agents)

Two shared keys are pre-configured in the package, so agents can read data and submit managed trades without handling a user's private key:

```typescript
import { GdexSkill, GDEX_API_KEY_PRIMARY } from '@gdexsdk/gdex-skill';

const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);
skill.isAuthenticated(); // → true
```

Read-only endpoints (`getTrendingTokens`, `getTokenDetails`, `getOHLCV`, `getTopTraders`) require **no** authentication.

### Managed-custody session keys

All trading runs through **server-side managed wallets**. The user's control wallet signs **once** (the sign-in message); on-chain execution is performed by GDEX backend trade workers. Write operations use a secp256k1 **session keypair** plus AES-256-CBC encrypted `computedData`:

```typescript
import {
  GdexSkill,
  GDEX_API_KEY_PRIMARY,
  generateGdexSessionKeyPair,
  buildGdexSignInMessage,
  buildGdexSignInComputedData,
} from '@gdexsdk/gdex-skill';

const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);
const apiKey = GDEX_API_KEY_PRIMARY;

// 1. Generate a session keypair
const { sessionPrivateKey, sessionKey } = generateGdexSessionKeyPair();

// 2. The control wallet signs the sign-in message (EIP-191 personal_sign)
const userId = '0xYourControlWallet';
const nonce = String(Math.floor(Date.now() / 1000) + Math.floor(Math.random() * 1000));
const message = buildGdexSignInMessage(userId, nonce, sessionKey);
// Sign `message` with the user's control wallet (EIP-191), e.g.:
//   const signature = await new ethers.Wallet(controlPrivateKey).signMessage(message);
const signature = await signWithControlWallet(message);

// 3. Submit the encrypted sign-in payload
const signIn = buildGdexSignInComputedData({ apiKey, userId, sessionKey, nonce, signature });
await skill.signInWithComputedData({ computedData: signIn.computedData, chainId: 622112261 });
```

{% hint style="info" %}
The encryption is **deterministic** AES-256-CBC: the key/IV are derived from `SHA256(apiKey)` — never use a random IV or the `iv:ciphertext` format. Sign-in is the only operation that uses EIP-191; all post-sign-in operations sign with the raw `keccak256` + secp256k1 session key (`v` = raw recovery param `00`/`01`). The **gdex-authentication** skill documents every helper.
{% endhint %}

***

## Skill Reference

### `gdex-spot-trading`

Buy and sell tokens across Solana, Sui, and EVM chains with automatic DEX routing.

```typescript
// Buy with native token (0.1 SOL)
const trade = await skill.buyToken({
  chain: 'solana',
  tokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: '0.1',
  slippage: 1,        // optional, default 1%
  dex: 'raydium',     // optional: force a DEX
});
// → { jobId, status, inputAmount, outputAmount, txHash?, error? }

// Sell an absolute amount
await skill.sellToken({ chain: 8453, tokenAddress: '0x...', amount: '100', slippage: 0.5 });

// Sell a percentage of holdings
await skill.sellToken({ chain: 'solana', tokenAddress: '...', amount: '50%' });
```

**Example prompts:** "Buy 0.1 SOL of USDC", "Sell 50% of my BONK", "Buy $50 of ARB on Arbitrum".

***

### `gdex-perp-trading`

HyperLiquid perpetual futures — open/close positions, set leverage, place market and limit orders with TP/SL.

```typescript
// Open a 10x BTC long with TP/SL
const pos = await skill.openPerpPosition({
  coin: 'BTC',
  side: 'long',
  sizeUsd: '1000',
  leverage: 10,
  takeProfitPrice: '110000',
  stopLossPrice: '95000',
  marginMode: 'cross',   // 'cross' (default) | 'isolated'
});

await skill.closePerpPosition({ coin: 'BTC' });                   // close 100%
await skill.closePerpPosition({ coin: 'ETH', closePercent: 50 }); // close 50%
await skill.setPerpLeverage({ coin: 'BTC', leverage: 20 });

const positions = await skill.getPerpPositions({ walletAddress: '0x...' });
```

**Example prompts:** "Open a 5x long on ETH with $200", "Close half my BTC short", "Set BTC leverage to 20x".

***

### `gdex-perp-funding`

Deposit and withdraw USDC to/from HyperLiquid (human-readable amounts, converted internally; 10 USDC minimum deposit).

```typescript
await skill.perpDeposit({ amount: '10' });  // deposit 10 USDC
await skill.perpWithdraw({ amount: '5' });   // withdraw 5 USDC
```

**Example prompts:** "Deposit 25 USDC to HyperLiquid", "Withdraw 10 USDC from my perp account".

***

### `gdex-limit-orders`

Create, update/delete, and list limit orders via managed-custody encrypted payloads. Endpoints are `limit_buy` / `limit_sell` / `update_order` / `orders`.

```typescript
// Limit buy with optional TP/SL
await skill.limitBuy({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: '0xControlWallet',
  sessionPrivateKey,
  chainId: 622112261,
  tokenAddress: 'EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm',
  amount: '10000000',        // lamports
  triggerPrice: '0.50',
  profitPercent: '50',       // optional TP
  lossPercent: '25',         // optional SL
});

// Delete an order (isDelete: true)
await skill.updateOrder({
  apiKey: GDEX_API_KEY_PRIMARY, userId: '0xControlWallet', sessionPrivateKey,
  chainId: 622112261, orderId: '<64-hex>', isDelete: true,
});

// List active orders (session-key auth)
// `data` is the encrypted session key from buildGdexUserSessionData(sessionKey, apiKey)
import { buildGdexUserSessionData } from '@gdexsdk/gdex-skill';
const encryptedSessionKey = buildGdexUserSessionData(sessionKey, GDEX_API_KEY_PRIMARY);
const { count, orders } = await skill.getLimitOrders({ userId, data: encryptedSessionKey, chainId: 622112261 });
```

**Example prompts:** "Buy TOKEN when it drops to $0.50", "Set a take-profit sell at $999", "Cancel my open limit order".

***

### `gdex-copy-trading`

Discover top wallets and create/manage **Solana** copy trades. Discovery is read-only; writes are Solana-only and sign in with `chainId: 622112261`.

```typescript
// Discovery (no auth)
const topWallets = await skill.getCopyTradeWallets();      // top 300 by total PnL
const gems = await skill.getCopyTradeGems();               // hot new tokens from top wallets

// Create a copy trade (computedData auth)
await skill.createCopyTrade({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId: controlWalletAddress,
  sessionPrivateKey,
  chainId: 622112261,
  traderWallet: 'SolanaTraderAddress',
  copyTradeName: 'Alpha Trader',
  buyMode: 1,                 // 1 = fixed SOL, 2 = percentage
  copyBuyAmount: '0.001',
  lossPercent: '50',
  profitPercent: '100',
  copySell: true,
});
```

{% hint style="warning" %}
There is no pause/toggle on the backend — both `isDelete: true` and `isChangeStatus: true` **permanently delete** a copy trade.
{% endhint %}

**Example prompts:** "Show the top Solana wallets by PnL", "Copy 0xLeader with 0.001 SOL per trade", "Delete my Alpha Trader copy trade".

***

### `gdex-perp-copy-trading`

Copy HyperLiquid perpetual-futures traders. Completely separate from Solana copy trading; sign-in uses `chainId: 1` and all ABI fields are strings.

```typescript
// Discovery (no auth)
const topByVolume = await skill.getHlTopTraders('volume');
const topByPnl = await skill.getHlTopTradersByPnl();
const stats = await skill.getHlUserStats('0xManagedWalletAddress'); // managed wallet, not control

// Create an HL copy trade (computedData auth)
await skill.createHlCopyTrade({
  apiKey, userId: controlWalletAddress, sessionPrivateKey,
  traderWallet: '0xTraderEvmAddress',
  copyTradeName: 'BTC Whale',
  copyMode: 1,                       // 1 = fixed USD, 2 = proportion
  fixedAmountCostPerOrder: '50',
  lossPercent: '25',                 // mandatory, 0 < x < 100
  profitPercent: '100',              // mandatory, > 0
  oppositeCopy: false,               // true = copy the opposite direction
});
```

**Example prompts:** "Who are the top HyperLiquid traders this week?", "Copy 0xWhale's perps at $50 per order", "Copy 0xTrader but inverted".

***

### `gdex-bridge`

Cross-chain bridging of native tokens between EVM chains, Solana, and Sui (via ChangeNow). Always quote first, then execute.

```typescript
import { ChainId } from '@gdexsdk/gdex-skill';

const quote = await skill.getBridgeQuote({
  fromChain: 'solana',
  toChain: ChainId.ETHEREUM,
  tokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: '100',
});
console.log(quote.outputAmount, quote.feeUsd);

const result = await skill.bridge({
  fromChain: 'solana',
  toChain: ChainId.ETHEREUM,
  tokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: '100',
  destinationAddress: '0xYourEthAddress',
  slippage: 0.5,
});
```

**Example prompts:** "Bridge 100 USDC from Solana to Ethereum", "What does it cost to bridge 0.5 ETH to Arbitrum?".

***

### `gdex-portfolio`

Cross-chain portfolio overview, chain-specific balances, and paginated trade history.

```typescript
import { ChainId } from '@gdexsdk/gdex-skill';

const portfolio = await skill.getPortfolio({ walletAddress: '0x...' });
// → { totalValueUsd, balances, perpPositions?, realizedPnl, unrealizedPnl }

const balances = await skill.getBalances({ walletAddress: '0x...', chain: ChainId.ETHEREUM });

const history = await skill.getTradeHistory({ walletAddress: '0x...', page: 1, limit: 20 });
```

**Example prompts:** "Show my portfolio across all chains", "What's my ETH balance on Base?", "List my last 20 trades".

***

### `gdex-token-discovery`

Token details, trending tokens, OHLCV candles, and top traders.

```typescript
const token = await skill.getTokenDetails({ tokenAddress: '...', chain: 'solana' });
// → { symbol, name, priceUsd, priceChange24h, marketCap, fdv, volume24h, liquidity }

const trending = await skill.getTrendingTokens({ chain: 'solana', period: '24h', limit: 20, minLiquidity: 50000 });

const ohlcv = await skill.getOHLCV({
  tokenAddress: 'So11111111111111111111111111111111111111112',
  chain: 'solana',
  resolution: '60', // '1'|'5'|'15'|'30'|'60'|'240'|'D'|'W'
  from: Math.floor(Date.now() / 1000) - 86400,
  to: Math.floor(Date.now() / 1000),
});

const traders = await skill.getTopTraders({ chain: 'solana', period: '7d', limit: 10, sortBy: 'pnl' });
```

**Example prompts:** "What's trending on Solana?", "Get the 1h candles for SOL", "Show the top traders this week".

***

### `gdex-livestream-discovery`

Solana livestream-token discovery — currently-live streams, per-token live status, and big-buy alert feeds. Useful for surfacing tokens with active community livestreams before momentum trades.

**Example prompts:** "Which Solana tokens are livestreaming right now?", "Is this token live?", "Show me the big-buy alert feed".

***

## Error Handling

The SDK throws typed errors so agents can recover gracefully:

```typescript
import {
  GdexAuthError,        // 401/403 — re-authenticate
  GdexValidationError,  // invalid params (.field)
  GdexApiError,         // 4xx/5xx (.statusCode)
  GdexNetworkError,     // connection failures, timeouts
  GdexRateLimitError,   // 429 — has .retryAfter (seconds)
} from '@gdexsdk/gdex-skill';
```

When something goes wrong, hand off to **gdex-sdk-debugging**, which maps error codes, encryption issues, and chain-specific gotchas to fixes.

***

**See also:**

* [🛠️ Platform & UI Skills](/gemach-dao/products/agent-skills/utility-skills.md) — onboarding, transfers, social, HyperLiquid extras, React UI, and debugging
* [✏️ Creating Custom Skills](/gemach-dao/products/agent-skills/creating-custom-skills.md) — build your own trading skill
* [🧩 Agent Skills Overview](/gemach-dao/products/agent-skills.md) — the complete catalog and install options


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gemach.io/gemach-dao/products/agent-skills/gdex-trading-skills.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.