gdex-portfolio
Cross-chain portfolio overview, chain-specific token balances, and paginated trade history
SKILL.mdskills/gdex-portfolio/SKILL.md
GitHubGDEX: Portfolio & Balances
Query cross-chain portfolio summaries, chain-specific balances, and trade history.
USDC across chains:
getUsdcBalancesreturns 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-skillinstalled- A managed session (control wallet + session key + API key, or
accountRefin 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
- Use
getPortfolio/getBalances/getTradingFunds/getTradeHistory; no raw-client workaround is needed. walletAddressis always the control wallet (GDEXuserId).- Reads are per chain: pass
chainevery time (Solana622112261). - 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