gdex-portfolio

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

SKILL.md

GitHub

GDEX: Portfolio & Balances

Query cross-chain portfolio summaries, chain-specific balances, and trade history.

USDC across chains: getUsdcBalances returns the user's USDC and gas balance on every USDC chain plus the total. See gdex-usdc-wallet.

When to Use

  • Reading a managed account's token holdings on a chain
  • Checking token balances or native trading funds on a specific chain
  • Retrieving trade history with cursor pagination

Prerequisites

  • @gemachdao/gdex-skill installed
  • A managed session (control wallet + session key + API key, or accountRef in MCP) — see gdex-authentication

Managed Holdings (getPortfolio)

/v1/portfolio is per chain and authenticated: userId (the control wallet, not the managed wallet) + encrypted session data + chainId. The SDK builds the query from your session; there is no public address-only holdings read.

import { GdexSkill, ChainId } from '@gemachdao/gdex-skill';

const skill = new GdexSkill();
const session = { walletAddress: controlAddress, sessionPrivateKey, apiKey };

const p = await skill.getPortfolio({ ...session, chain: ChainId.SOLANA });
// { status: 'ok', mode: 'managed', userId, chainId, holdings: Balance[], balances: (same) }
for (const h of p.holdings) console.log(h.symbol, h.balance, h.rawBalance);

Pass data (from buildGdexReadSessionData(sessionPrivateKey, apiKey)) instead of sessionPrivateKey + apiKey if you already have it. In MCP, pass accountRef.

interface Balance {
  tokenAddress: string;
  symbol: string;
  name: string;
  decimals: number;
  rawBalance: string;      // exact integer base units
  balance: string;         // exact decimal of rawBalance
  priceUsd?: string;
  usdValue?: string;
  priceNative?: string;
  valueNative?: string;    // backend `holding` (current worth, native)
  investedNative?: string; // backend `invested`
  pnlPercentage?: number;
  chain: number;
  chainId?: number;
}

Failures are errors, not zeros. A refused session (400 code 102/104) or a response without holding[] throws; [] only ever means the backend answered with no holdings.

Balances and Trading Funds

// Token balances on one chain (optionally one token)
const usdc = await skill.getBalances({ ...session, chain: 8453, tokenAddress: '0x8335...' });

// Native balance available to trade (GET /v1/user)
const funds = await skill.getTradingFunds({ ...session, chain: 8453 });
// { address (managed wallet), nativeBalance, nativeSymbol, walletsByChain, precision: 'approximate' }

nativeBalance is a backend float, and the backend reports 0 when its RPC read fails, so treat a zero as unconfirmed. Cross-chain USDC: getUsdcBalances (gdex-usdc-wallet).

Trade History

/v1/user_history is keyed by the control wallet (user) and chainId; it needs no session. Cursor pagination, at most 50 per page:

let page = await skill.getTradeHistory({ walletAddress: controlAddress, chain: 8453, limit: 50 });
while (page.nextCursor) {
  page = await skill.getTradeHistory({ walletAddress: controlAddress, chain: 8453, cursor: page.nextCursor });
}
// page.trades: TradeRecord[] — { type: 'buy'|'sell', tokenAddress, tokenAmount, nativeAmount (raw), txHash, timestamp, ... }

page, startTime and endTime are not supported by the backend and are rejected. The backend returns an empty page on its own database errors, so an empty page is not proof of no trades.

Autonomous Agent Notes

  1. Use getPortfolio / getBalances / getTradingFunds / getTradeHistory; no raw-client workaround is needed.
  2. walletAddress is always the control wallet (GDEX userId).
  3. Reads are per chain: pass chain every time (Solana 622112261).
  4. For percentage sells, sellToken({ amount: '50%' }) reads the holding itself (gdex-spot-trading).

Related Skills

  • gdex-authentication — Auth setup required for portfolio queries
  • gdex-spot-trading — Execute trades based on portfolio analysis
  • gdex-perp-trading — View perp positions in portfolio
  • gdex-token-discovery — Research tokens found in portfolio