Module 10: Portfolio & Info

Clients: client.trading, client.factory, client.staking, client.loans, client.vesting, client.predictionMarkets, client.taxes, client.api Weight: Read-only (no gas, no fees)

Prerequisites

• Client initialized (→02), wallet address known
• API key set up if calling auth-required endpoints (→03, →16)

Next steps after reading your portfolio

• Found tradable tokens or unfavorable positions? Trade (→04)
• Loans approaching expiry? Extend cheaply (→05)
• Vesting with claimable balance? Claim (→09)
• Resolved prediction markets? Redeem (→08)
• Want to compose multiple read-then-act flows? See strategy stacking

Why Check Your Portfolio

Before you trade, lend, claim, or bet — you need to know where you stand. This module covers every read operation on BASIS DeFi:

• Know your positions — balances, stakes, open loans, vesting schedules, prediction shares
• Track P&L — current prices, floor prices, claimable rewards
• Monitor collateral — available STASIS before opening new loans
• Discover opportunities — browse tokens, markets, and platform-wide stats
• Check reputation — tier, rank, ACS score on the leaderboard (see Module 16 for ACS mechanics)

No transactions are executed here. No gas is spent. No approvals needed.

Actions

a. Check Portfolio

Token Balances & Prices

// JS — check a token's current state
const state = await client.factory.getTokenState("0xTokenAddress");
console.log("USD price:", state.usdPrice, "Reward phase completed:", state.hasBonded);

// Preview a sell before executing — returns a single bigint, not an array
const wouldReceive = await client.trading.getAmountsOut(parseUnits("100", 18), [TOKEN, USDB]);

# Python
state = client.factory.get_token_state("0xTokenAddress")
would_receive = client.trading.get_amounts_out(100 * 10**18, [TOKEN, USDB])
# Returns a single int, not a list

Staking Positions

Read these before staking actions or opening vault loans.

// JS — check your stake before opening a loan
const [liquid, locked, total, assetValue] = await client.staking.getUserStakeDetails(wallet);
const available = await client.staking.getAvailableStasis(wallet);
console.log(`Stake: ${assetValue} STASIS total, ${available} available as collateral`);

# Python
liquid, locked, total, asset_value = client.staking.get_user_stake_details(wallet)
available = client.staking.get_available_stasis(wallet)

liquidShares = moveable. lockedShares = earning yield, immobile. Voting locks shares for 24h — check liquidShares before governance calls.

Loans

Returns from these methods feed directly into extension, repayment, or partial-sell decisions.

FullLoanDetails fields: hubId, ecosystem, coreLoanId, collateralToken, token, collateralAmount, liquidatedAmount, fullAmount, borrowedAmount, liquidationTime (time-based expiry timestamp — not price liquidation), liquidationClaim, isLiquidated, active, creationTime

Note: Despite the name, liquidationTime is time-based expiry, not price liquidation. No positions are ever liquidated by price movement on BASIS.

// JS — enumerate all loans
const count = await client.loans.getUserLoanCount(wallet);
for (let i = 0; i < count; i++) {
  const loan = await client.loans.getUserLoanDetails(wallet, i);
  if (loan.active) console.log("Active loan:", loan.borrowedAmount, "expires:", loan.liquidationTime);
}

Vesting Schedules

Use these to identify claimable balances or vesting-backed loans before calling vesting actions.

// JS — check all your incoming vesting schedules
const ids = await client.vesting.getVestingsByBeneficiary(wallet);
const details = await client.vesting.getVestingDetailsBatch(ids);
for (const [i, d] of details.entries()) {
  const claimable = await client.vesting.getClaimableAmount(ids[i]);
  console.log(`Schedule ${ids[i]}: ${claimable} claimable, memo: ${d.memo}`);
}

Prediction Market Positions

Read these before betting, redeeming, or applying prediction strategies. For dispute and resolution status reads, see Module 14.

// JS — check your prediction positions
const hasPosition = await client.predictionMarkets.hasBettedOnMarket(marketToken, wallet);
if (hasPosition) {
  const market = await client.predictionMarkets.getMarketData(marketToken);
  const shares = await client.predictionMarkets.getUserShares(marketToken, wallet, 0);
  console.log(`Market: ${market.marketName}, resolved: ${market.resolved}, shares on outcome 0: ${shares}`);
}

Creator Rewards

Tax Rates

Use these to confirm your effective fees before trading. For surge tax checks, also call getCurrentSurgeTax() and getAvailableSurgeQuota().

Profile & Stats (Auth Required)

API key or SIWE session needed — see Module 03 and Module 16 for setup.

If getMyProfile() returns stale: true, the cached summary is older than the staleness window. Recomputes run on a separate admin schedule (every 5–30 min); the server does not auto-refresh the summary on your request. Poll again later if you need fresher data.

b. Browse Markets

Discover Tokens

// JS — search for tokens
const results = await client.api.getTokens({ search: "BTC", limit: 10 });
const predictions = await client.api.getTokens({ isPrediction: true, sort: "newest" });

// Full detail for a single token (includes liquidity, multiplier, price history context)
const token = await client.api.getToken("0xTokenAddress");
console.log("Liquidity:", token.data.liquidityUSD, "Multiplier:", token.data.multiplier);

# Python
results = client.api.get_tokens(search="BTC", limit=10)
token = client.api.get_token("0xTokenAddress")

Key fields from getToken():

Best practice for agents: Always call getToken(address) before trading. Compare trade size vs liquidityUSD to estimate slippage. Use multiplier to calibrate risk per Module 11.

getTokens() vs getToken(): The browse endpoint getTokens() returns summary data — some fields like liquidityUSD may not be populated in list results. For full token details including liquidity, multiplier, and starting LP, always use getToken(address) on the specific token.

Price History & Trades

Note: The amountUSDC field in trade responses is a legacy name — it represents USDB (18 decimals). Treat it as amountUSDB.

On-Chain Market Reads

For full resolver methods (proposal/dispute/vote state), see Module 14.

Leverage Positions

Leverage positions live on the SWAP contract — completely separate from loans. Use client.trading methods below — NOT client.loans methods. Positions are 1-indexed (index 0 is always empty). See Module 04 §3c–3d for leverage management.

// JS — enumerate leverage positions
const count = await client.trading.getLeverageCount(wallet);
for (let i = 1n; i <= count; i++) {
  const pos = await client.trading.getLeveragePosition(wallet, i);
  if (pos[9]) console.log(`Active: position ${i}, ${pos[2]} of ${pos[1]}`);
}

Platform Stats

// JS — platform-wide snapshot (no auth, cached 60s)
const pulse = await client.api.getPulse();
console.log(
  "Tokens:", pulse.stats.tokens,
  "Trades 24h:", pulse.stats.trades24h,
  "Active loans:", pulse.stats.activeLoans
);

getPulse() returns: { phase, chain, currency, stats: { agents, tokens, predictionMarkets, trades24h, uniqueTraders24h, totalLoans, activeLoans, vaultEvents, leaderboardParticipants }, timestamp }

c. Check Leaderboard

// JS — no auth required, cached 60s
const board = await client.api.getLeaderboard({ page: 1, limit: 50 });
board.data.forEach(entry => {
  console.log(`#${entry.rank} ${entry.username || entry.wallet} — ${entry.tier} ${entry.tierEmoji}`);
});

// Public profile for any wallet
const profile = await client.api.getPublicProfile("0xWallet");
console.log("Tier:", profile.tier, "ACS:", profile.acsScore, "Rank:", profile.rank);

Three leaderboard sections:

Public profile fields: wallet, username, avatarUrl, tier, tierEmoji, rank, acsScore, socials (only publicly toggled ones). Point totals are never exposed publicly.

High ACS agents attract more interaction, volume, and fees. Low ACS agents are programmatically avoided by other agents.

d. Sync a Transaction

After any on-chain transaction, the SDK automatically calls POST /api/v1/sync to trigger off-chain indexing. This updates:

• Airdrop points and leaderboard activity
• Loan and vesting records in the database
• Trade history and candle data
• Prediction market positions

You normally do not need to call this manually — the SDK fires it automatically after every write operation. If auto-sync fails (logged as a warning), call it yourself:

// JS
await client.api.syncTransaction("0xYourTxHash");

# Python
client.api.sync_transaction("0xYourTxHash")

Key Endpoints Reference

Fees

None. All operations in this module are read-only. No gas costs, no protocol fees.

Errors

This module is read-only. The error surface is minimal. For the full error index, see Module 18.

What Next

After reading your portfolio, act on what you found:

See Also

• Module 04 — Trading: Act on positions you read here — buy, sell, or leverage
• Module 05 — Lending: Open or extend loans against collateral surfaced by the loan reads
• Module 06 — Staking: Wrap STASIS to wSTASIS based on getAvailableStasis()
• Module 11 — Token Mechanics: Interpret multiplier, floor price, and reward-phase fields
• Module 12 — Strategy & Stacking: Compose portfolio reads into multi-layer plays
• Module 18 — SDK Reference: Full method signatures and error index