Skip to main content

TypeScript Client Reference

MagmaClient composes ten resource clients, each exposed as a property. This page documents every method the SDK actually implements — its parameters, return type, and a short example.

import { MagmaClient } from '@magma-protocol/sdk';

const magma = new MagmaClient(/* options */);
PropertyClassSummary
magma.narrativesNarrativesResourceBrowse, fetch, back, prepare, challenge, and AI-polish narratives.
magma.oracleOracleResourceOracle scores, source statuses, and audit trails.
magma.usersUsersResourceProfiles, conviction, backings, streaks, history.
magma.novaNovaResourceEcho Pool epoch state, history, and tickets.
magma.defiDeFiResourceLive APYs, positions, and supported tokens.
magma.leaderboardLeaderboardResourceConviction and streak leaderboards.
magma.categoriesCategoriesResourceNarrative categories.
magma.configConfigResourcePublic protocol parameters.
magma.botBotResourceAI polish and originality checks.
magma.adminAdminResourceFeatured management and dashboard (admin auth).
Not yet available

A few methods target endpoints that do not exist on the backend yet and are marked Not yet available (pending backend) below. Calling them today will return an error. They are included because the typed signatures ship with the SDK.

All HTTP-level behavior (auth headers, GET-only retries, timeouts, MagmaError) is described in Error handling.

narratives​

NarrativesResource — the full narrative lifecycle.

feed(params?)​

Get the paginated narrative feed.

  • Params: NarrativeFeedParams (optional)
    • filter?: 'all' | 'active' | 'new' | 'backed'
    • category?: string
    • sort?: 'newest' | 'most_backed' | 'ending_soon' | 'top_score'
    • status?: 'active' | 'resolved_true' | 'resolved_false' | 'under_review'
    • page?: number
    • limit?: number
  • Returns: Promise<NarrativeFeedResponse> — { narratives: Narrative[]; total: number; page: number; has_more: boolean }

The backend root feed returns only { narratives }; the SDK normalizes the response, defaulting total to the returned count, page to the requested page (or 1), and has_more to false.

const { narratives, total } = await magma.narratives.feed({ filter: 'active', limit: 20 });

get(id)​

Get a single narrative by ID. Unwraps the backend { narrative } envelope.

  • Params: id: string
  • Returns: Promise<Narrative>
const narrative = await magma.narratives.get('<NARRATIVE_ID>');

getScoreHistory(id, window?)​

Oracle score history for sparkline charts.

  • Params: id: string, window: '7d' | '30d' | 'all' (default '7d')
  • Returns: Promise<{ scores: ScoreHistoryPoint[] }>
const { scores } = await magma.narratives.getScoreHistory('<NARRATIVE_ID>', '30d');

getBackers(id, limit?)​

Backers for a narrative.

  • Params: id: string, limit: number (default 20)
  • Returns: Promise<{ backings: any[]; total_backed_sol: number; unique_backers: number }>

getOpposing(id)​

The opposing narrative, if one exists.

  • Params: id: string
  • Returns: Promise<{ opposing: Narrative | null }>

back(id, params)​

Record a backing on a narrative. Requires auth. This is a POST and does not auto-retry.

  • Params: id: string, params: BackingParams
    • sol_amount: number
    • token_address: string
    • tx_signature: string
    • referral_farcaster_fid?: number
  • Returns: Promise<BackingResponse>

The SDK maps the public params onto the backend body (amount_sol, token_type, tx_signature, referral_farcaster_fid) and returns the full response:

interface BackingResponse {
  success: boolean;
  backing: NarrativeBackingRow; // the complete narrative_backings DB row
  yield: BackingYield | null;   // Kamino deposit result, or null
}

NarrativeBackingRow carries the full database row (53 columns; the modelled fields include id, narrative_id, wallet_address, amount_sol, token_type, usd_equivalent, the multiplier breakdown, epoch_number, and settlement columns, with an index signature for the rest). BackingYield is present only when SOL routed into Kamino — { active: boolean; estimatedApy?: number; receipt?: string } — and is null otherwise.

const result = await magma.narratives.back('<NARRATIVE_ID>', {
  sol_amount: 0.5,
  token_address: 'SOL',
  tx_signature: '<SIGNATURE>',
});

console.log(result.success, result.backing.epoch_number);
if (result.yield) console.log(result.yield.active, result.yield.estimatedApy);

prepareMint(params)​

Prepare the unsigned backing transaction (gasless via Kora if configured). POST.

  • Params:
    • narrative_id: string
    • backer_wallet: string
    • amount_sol?: number
    • amount_usdc?: number
    • token_type?: string
  • Returns: Promise<{ transaction: string; narrativeId: string; deadlineTimestamp: number; gasless: boolean; koraFeeEstimate: number }>
const { transaction, gasless } = await magma.narratives.prepareMint({
  narrative_id: '<NARRATIVE_ID>',
  backer_wallet: '<WALLET>',
  amount_sol: 0.5,
});

challenge(id, params)​

Submit a challenge on a resolved narrative. Requires auth. POST.

  • Params: id: string, params: { reason: string; evidence_url?: string; tx_signature: string }
  • Returns: Promise<{ challenge_id: string; tier: 'T1' | 'T2' | 'T3'; estimated_resolution_hours: number }>

getChallenges(id)​

Challenges for a narrative.

  • Params: id: string
  • Returns: Promise<{ challenges: any[] }>

polish(params)​

Polish a narrative thesis with AI. POST.

  • Params: { thesis: string; wallet_address?: string }
  • Returns: Promise<{ polished: string; score: number }>

checkOriginality(params)​

Check a thesis for originality against existing narratives. POST.

  • Params: { thesis: string; wallet_address?: string }
  • Returns: Promise<{ is_original: boolean; similarity_score: number; similar_narratives: any[] }>

getFeatured()​

Featured narratives for the hero carousel.

  • Returns: Promise<FeaturedResponse> — { featured: Narrative[]; last_updated: string | null; next_rotation: string | null }

oracle​

OracleResource — oracle scores and resolution data.

Not yet available (pending backend)

Every method on this resource targets a route that does not exist yet. The typed signatures ship with the SDK, but calls will fail until the backend routes land.

getScore(narrativeId) — not yet available (pending backend)​

  • Params: narrativeId: string
  • Returns: Promise<OracleScore> — { score, confidence, trend: 'up' | 'down' | 'flat', sources: OracleSource[], last_evaluated_at }

getSources() — not yet available (pending backend)​

  • Returns: Promise<{ sources: any[] }>

getAudit(narrativeId) — not yet available (pending backend)​

  • Params: narrativeId: string
  • Returns: Promise<{ logs: any[]; resolution_sources: string[]; resolution_confidence: number }>

For oracle score history that is available today, use narratives.getScoreHistory().

users​

UsersResource — user and conviction data.

getProfile(wallet)​

Public user profile.

  • Params: wallet: string
  • Returns: Promise<UserProfile>

getConvictionProfile(wallet)​

Full conviction profile with per-category stats.

  • Params: wallet: string
  • Returns: Promise<UserProfile>
const profile = await magma.users.getConvictionProfile('<WALLET>');
console.log(profile.conviction_tier, profile.conviction_score);

getBackings(wallet, params?)​

A wallet's narrative backings.

  • Params: wallet: string, params?: { status?: string; page?: number }
  • Returns: Promise<{ backings: any[]; total_backed_sol: number }>

getStreak(wallet)​

Eruption Streak state.

  • Params: wallet: string
  • Returns: Promise<EruptionStreak> — { current_streak, streak_tier, forge_multiplier, echo_ticket_multiplier, last_correct_at, all_time_peak }

getHistory(wallet, params?)​

Transaction history. Requires auth (own wallet).

  • Params: wallet: string, params?: { type?: string; page?: number }
  • Returns: Promise<{ transactions: any[] }>

nova​

NovaResource — Echo Pool epochs.

getEpoch()​

Current epoch state.

  • Returns: Promise<EpochState> — { epoch_number, echo_pool_sol, days_remaining, total_tickets, unique_participants, epoch_start, epoch_end }
const epoch = await magma.nova.getEpoch();

getEpochHistory(page?)​

Historical epoch results.

  • Params: page: number (default 1)
  • Returns: Promise<{ epochs: any[]; total_distributed_all_time_sol: number }>

getTickets(wallet) — not yet available (pending backend)​

Per-wallet ticket count. Requires auth.

Not yet available (pending backend)

This method targets a route that does not exist yet; calls will fail until the backend route lands.

  • Params: wallet: string
  • Returns: Promise<{ tickets: number; base_tickets: number; streak_bonus_tickets: number; rank: number; win_probability_pct: number }>

defi​

DeFiResource — yield rates and positions across the MAGMA DeFi set (Kamino, Save, Jito, Marinade, Jupiter, Meteora, Guardian, P0).

getApys()​

Live APY rates from all yield sources.

  • Returns: Promise<{ sources: any[] }>

getPositions(wallet)​

Active DeFi positions for a wallet. Requires auth.

  • Params: wallet: string
  • Returns: Promise<{ positions: any[] }>

getTokens()​

Supported token/protocol list, derived from /v1/defi/apys. There is no standalone tokens route; the SDK joins the protocols metadata with the apys map and returns one entry per protocol.

  • Returns: Promise<{ tokens: DeFiToken[] }>
interface DeFiToken {
  protocol: string;          // e.g. 'kamino'
  label: string;             // e.g. 'Kamino Lend'
  token: string;             // e.g. 'SOL/USDC'
  apy?: number;              // live APY (percent), if available
  testnet_available: boolean;
  coming_at: string | null;  // when it goes live if not yet, else null
}
const { tokens } = await magma.defi.getTokens();

leaderboard​

LeaderboardResource.

get(params?)​

Ranked leaderboard.

  • Params: params?: { sort?: string; tier?: string; limit?: number }
  • Returns: Promise<{ leaders: LeaderboardEntry[] }> — each { rank, wallet, score, tier, accuracy_pct, total_backed_sol }

getStreaks()​

Streak leaderboard.

  • Returns: Promise<{ leaders: any[] }>

categories​

CategoriesResource.

getAll()​

All narrative categories.

  • Returns: Promise<{ categories: Category[] }> — each { id, name, oracle_sources, is_fast, color }

config​

ConfigResource.

getPublic()​

Public protocol configuration (fees, limits, feature flags). Values are returned as strings by the backend.

  • Returns: Promise<PublicConfig>
interface PublicConfig {
  min_narrative_launch_usd: string;
  max_backing_usd: string;
  min_backing_usd: string;
  challenge_fee_sol: string;
  protocol_fee_pct: string;
  echo_pool_enabled: string;
  settlement_time_utc: string;
  fast_narrative_enabled: string;
  categories: string[];
  fast_categories: string[];
}

bot​

BotResource — AI helpers. These map to the same backend routes as the narratives AI methods.

polish(params)​

  • Params: { thesis: string; wallet_address?: string }
  • Returns: Promise<{ polished: string; score: number }>

checkOriginality(params)​

  • Params: { thesis: string; wallet_address?: string }
  • Returns: Promise<{ is_original: boolean; similarity_score: number; similar_narratives: any[] }>

admin​

AdminResource — admin auth required.

setFeatured(narrativeIds)​

Set the featured narratives. PUT.

  • Params: narrativeIds: string[]
  • Returns: Promise<FeaturedResponse>

getDashboard()​

Admin dashboard stats. Targets the root /admin/stats route (not under /v1).

  • Returns: Promise<any>

See also​