GDEX: Spot Trading

Buy and sell tokens across Solana, Sui, and 12+ EVM chains. The SDK routes through the best available DEX automatically, or you can specify one.

When to Use

• Buying a token with native currency (SOL, ETH, etc.)
• Selling a token (absolute amount or percentage of holdings)
• Executing managed-custody spot trades with encrypted payloads

Prerequisites

• @gdexsdk/gdex-skill installed
• Authenticated via loginWithApiKey() or managed-custody sign-in
• See gdex-authentication for auth setup

Buy a Token

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

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

const trade = await skill.buyToken({
  chain: 'solana',                                        // chain name or ChainId number
  tokenAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC on Solana
  amount: '0.1',                                          // 0.1 SOL (native token input)
  slippage: 1,                                            // 1% max slippage (optional, default: 1)
  dex: 'raydium',                                         // optional: prefer a specific DEX
});
// Returns: { jobId, status, inputAmount, outputAmount, txHash?, error? }

Parameters

Critical: The Solana numeric chainId is 622112261 (ChainId.SOLANA), NOT 900. Using 900 returns the EVM managed address with balance: null. The /v1/user endpoint returns a different managed wallet per chainId (e.g. CFSi4Y... for Solana, 0x9967... for EVM). | | tokenAddress | string | Yes | Contract address of the token to buy | | amount | string | Yes | Amount of native token to spend (e.g., '0.1' for 0.1 SOL) | | slippage | number | No | Max slippage % (default: 1) | | dex | string | No | Force specific DEX: 'raydium', 'orca', 'uniswap-v3', 'cetus', etc. | | walletAddress | string | No | Override wallet address | | priorityFee | number | No | Solana priority fee in lamports |

Sell a Token

// Sell absolute amount
const trade = await skill.sellToken({
  chain: 8453,                                            // Base
  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
  amount: '100',                                          // sell 100 tokens
  slippage: 0.5,
});

// Sell percentage of holdings
const trade = await skill.sellToken({
  chain: 'solana',
  tokenAddress: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263', // BONK
  amount: '50%',                                          // sell 50% of holdings
});

Parameters

Managed-Custody Trade Submission

For full managed-custody trading with encrypted payloads:

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

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

// Build encrypted trade payload (requires session key from sign-in)
const trade = buildGdexManagedTradeComputedData({
  apiKey: GDEX_API_KEY_PRIMARY,
  action: 'purchase',  // or 'sell'
  userId: '0xYourAddress',
  tokenAddress: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
  amount: '100000',     // in smallest unit
  nonce: String(Math.floor(Date.now() / 1000) + Math.floor(Math.random() * 1000)),
  sessionPrivateKey,    // from generateGdexSessionKeyPair()
});

const result = await skill.submitManagedPurchase({
  computedData: trade.computedData,
  chainId: 622112261,   // 622112261=Solana (ChainId.SOLANA), NOT 900
  slippage: 15,          // 10-15% recommended for Solana
});

Solana-Specific Notes (Live-Tested)

• Raydium-routed tokens work; Meteora tokens fail. The backend has a bug where Meteora DLMM swaps don't wrap SOL into WSOL before swapping. Check token.dexId — if "meteora", the swap will fail with Program error: 1. Tokens with dexId: "raydium" work correctly.
• Minimum ~0.01 SOL balance needed. Each new token ATA costs ~0.002 SOL rent + priority fee (0.0005 default) + base tx fee. The first trade on a token needs significantly more SOL than just the swap amount.
• Amount is in lamports (1 SOL = 1,000,000,000 lamports). Pass as a string, e.g. '5000000' for 0.005 SOL.
• Use chainId: 622112261, not 900. Using 900 will submit the trade to the wrong chain context.

Trade Status Polling

if (result.requestId) {
  const status = await skill.getManagedTradeStatus(result.requestId);
  console.log('Status:', status.status, 'Hash:', status.hash);
}

Status values:

• 'queued' — submitted to queue
• 'pending' — being processed
• 'completed' — executed on-chain
• 'failed' — failed (check error field)

Supported Chains × DEXes

Error Handling

import { GdexValidationError, GdexApiError, GdexRateLimitError } from '@gdexsdk/gdex-skill';

try {
  await skill.buyToken({ chain: 'solana', tokenAddress: '...', amount: '0.1' });
} catch (err) {
  if (err instanceof GdexRateLimitError) {
    await delay(err.retryAfter * 1000);  // wait and retry
  } else if (err instanceof GdexValidationError) {
    console.error('Invalid param:', err.message);
  } else if (err instanceof GdexApiError) {
    console.error('API error:', err.status, err.message);
  }
}

Notes

• All amounts are strings to preserve precision (e.g., '0.1', '1000')
• Chain can be string ('solana') or ChainId number (622112261)
• The SDK retries on transient errors (429, 503) with exponential backoff
• If no dex specified, the backend selects the best route automatically

Autonomous Agent Notes (Live-Tested)

Managed-Custody Trades Require Raw Units

For buildGdexManagedTradeComputedData() + submitManagedPurchase() / submitManagedSell(), the amount must be in raw units (lamports for Solana, wei for EVM), NOT human-readable:

// ❌ WRONG: amount: '0.01' (this is a float, not raw units)
// ✅ CORRECT: amount: '10000000' (0.01 SOL = 10,000,000 lamports)
// ✅ CORRECT: amount: '10000000000000000' (0.01 ETH = 10^16 wei)

Raydium vs Meteora on Solana

• Raydium-routed tokens work correctly (WIF, most liquid tokens)
• Meteora DLMM tokens fail with Program error: 1 (backend bug — doesn't wrap SOL into WSOL)
• Check before buying: token.dexId === 'raydium' ✅ / token.dexId === 'meteora' ❌
• If you get Program error: 1, the token is Meteora-routed — don't retry, pick a different token

Minimum SOL Balance

Keep at least 0.01 SOL in the managed Solana wallet. First trade on a new token costs ~0.007 SOL overhead (ATA creation + priority fee + base tx fee) on top of the trade amount.

Trade Status Polling

After a managed trade returns a requestId, poll until status === 'completed':

if (result.requestId) {
  let status;
  do {
    await new Promise(r => setTimeout(r, 3000)); // wait 3s between polls
    status = await skill.getManagedTradeStatus(result.requestId);
  } while (status.status === 'queued' || status.status === 'pending');
  console.log('Final:', status.status, status.hash);
}

Sell by Percentage

To sell a portion of holdings, use amount: '50%' (string with % sign). The backend calculates the exact token amount.

Related Skills

• gdex-authentication — Auth setup required before trading
• gdex-portfolio — Check balances and trade history after trading
• gdex-token-discovery — Research tokens before buying (no auth needed)
• gdex-limit-orders — Set limit orders instead of market buys/sells