Module 10: Portfolio & Info

Clients: client.trading, client.factory, client.vault(main), 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

Examples use the default main, STASIS, whose pair asset is USDG. On another main read "USDG" as that main's pair asset and use its decimals(). The mains of a deployment are listed in /contracts.json (mains[]).

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: STASIS free to pledge in the vault before opening new loans
• Discover opportunities: browse tokens, markets, and platform-wide stats
• Check reputation: ACS score, and the old leaderboard, now frozen (see Module 16)

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("Pair price:", state.pairPrice, "Presale complete:", state.presaleComplete);

// Preview a sell before executing: returns a single bigint, not an array
// MAIN = the token's main (token.quoteToken()); PAIR_ASSET = that main's pair asset (SWAP.pairs(MAIN).pairAsset)
const wouldReceive = await client.trading.getAmountsOut(parseUnits("100", 18), [TOKEN, MAIN, PAIR_ASSET]); // before the trade fee

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

Vault Positions (per main)

Read these before staking actions or opening vault loans. One vault serves every main, with its own pool for each main: SWAP.pairs(main).staking (the vault field of /contracts.json mains[]). The stake is 1:1; there is no receipt token and no share price.

// JS: check your stake before opening a loan
const pos = await client.vault().getPosition(wallet);          // the default main's vault
const available = await client.vault().getAvailableStasis(wallet);
console.log(`Stake: ${pos.staked} STASIS, ${available} available to pledge`);

# Python
pos = client.vault().get_position(wallet)
available = client.vault().get_available_stasis(wallet)

staked includes the pledged part. pledged backs the open loan and cannot be unstaked. Nothing is locked by a resolver vote.

Loans

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

FullLoanDetails fields: hubId, ecosystem, coreLoanId (the loan's internal id), collateralToken, token, collateralAmount, liquidatedAmount, fullAmount, borrowedAmount, liquidationTime (time-based expiry timestamp, not price liquidation), liquidationClaim, isLiquidated, active, creationTime. Amounts (fullAmount, borrowedAmount) are in the pair asset of the loan's main (ecosystem).

Note: Despite the name, liquidationTime is time-based expiry, not price liquidation. No positions are ever liquidated by price movement on BASIS. After liquidationTime a keeper liquidates the position. Assume it can happen in the first block after the deadline. Until that transaction lands a repay or a paid extension still goes through; do not plan on the gap. The keeper closes the loan: the collateral that covers the debt is taken to repay it, 10% of the rest is the liquidation fee, and you claim the remainder. Claim within 365 days of the liquidation; after that the leftover may no longer be claimable.

// JS: enumerate all loans (hub ids start at 1)
const count = await client.loans.getUserLoanCount(wallet);
for (let id = 1n; id <= count; id++) {
  const loan = await client.loans.getUserLoanDetails(wallet, id);
  if (loan.active) console.log("Active loan:", loan.borrowedAmount, "expires:", loan.liquidationTime);
}

Id 0 and any id above the count revert "Loan does not exist". A vault loan is held by the vault in the hub: read it through the vault's positions(main, user).hubId and hub.

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}`);
}

Holder Rewards

A creator's income is not here: the creator fee is paid out on every trade, and nothing is claimed for it.

Tax Rates

Use these to confirm your effective fees before trading. Rates are read, never assumed: the base can change and a creator can change a token's fees every 4 hours.

On-Chain Referrals, Creator Earnings and Mains

Contract reads with no SDK wrapper of their own today (call them on the contract, or through the handoff names under the marker).

Fees a wallet has paid have no on-chain total. They come from the API.

Profile & Stats (Auth Required)

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

totalTrades counts one per swap, not per pool leg. marketWins counts distinct markets you redeemed a payout from, INVALID refunds left out.

If getMyProfile() returns stale: true, the cached summary is older than the staleness window. Recomputes run on a separate 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("Depth (USD x 1e18):", token.data.depthUsdE18, "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 depthUsdE18 (divide by 1e18) to estimate slippage. Use multiplier to calibrate risk per Module 11.

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

Price History & Trades

Note: amountUSDC is a legacy name, kept for one release. It is the quote amount of the leg: main-token units (18 decimals) on a factory token, raw pair-asset units on a main. Read amountQuote, quoteAsset and quoteDecimals; the USD value is valueUsdE18 (null when unknown). price is raw pair-asset units per whole token, taken before the trade on buy, sell and leverage_buy rows and after it on leverage_sell rows.

On-Chain Market Reads

For full resolver methods (proposal/dispute/vote state), see Module 14. The chain has no market list: list markets with client.api.getTokens({ isPrediction: true }). Private markets are read the same way through client.privateMarkets (the private host).

The pot. Sum totalCost over getAllOutcomes(host, market): the pot is in market tokens. Value it in the pair asset with TrancheReader.valueInUsdb(host, market, amount). getMarketData().generalPot always reads 0: it is not the pot.

Leverage Positions

Your leverage positions are recorded on each main and are opened and closed through SWAP. They are not hub loans: use client.trading methods below, NOT client.loans methods. Ids count from 1, per main (index 0 is always empty). See Module 04 §3c–3d for leverage management.

// JS: enumerate leverage positions on one main (repeat for each main in /contracts.json mains[])
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; 24h figures cached 10s, all-time / 7d / 30d cached 120s)
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, totalLoans, activeLoans, vaultEvents, leaderboardParticipants, txnTotal, txn24h, txn7d, txn30d, tradesTotal, trades24h, uniqueTradersTotal, uniqueTraders24h, volumeTotalUSD, volume24hUSD, volume7dUSD, volume30dUSD, volumePerDay30dUSD, avgTradeUSD, assetsCreated, volumeByPairAsset }, timestamp }. USD figures are null when a row in the window has no USD value.

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);

getLeaderboard returns the old leaderboard: its final standings, frozen for good (frozen: true, takenAt says when they were recorded). The site no longer scores points, so the ranks and tiers there do not change. The app also shows a live PNL board.

Public profile fields: wallet, username, avatarUrl, tier, tierEmoji, rank, acsScore, socials (only publicly toggled ones). tier and rank come from the frozen leaderboard.

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. The server decodes every BASIS event of the transaction in one call: trades, fees, referrals, loans, vault, vesting, markets and Up/Down. Transactions you did not send (a keeper liquidating your loan, another wallet filling your order) are indexed by the platform's worker.

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: Stake STASIS; getAvailableStasis() is what you can pledge
• Module 11: Token Mechanics: Interpret multiplier, floor price, and presale fields
• Module 12: Strategy & Stacking: Compose portfolio reads into multi-layer plays
• Module 18: SDK Reference: Full method signatures and error index