Skip to main content

Installation & Setup

The MAGMA TypeScript SDK (@magma-protocol/sdk) is a typed, tree-shakeable client for the MAGMA REST API. It wraps every resource with full type definitions and handles base URLs, auth headers, retries, and request timeouts for you.

Beta

The SDK targets the MAGMA API on Solana devnet. Interfaces are stabilizing but may still change before the mainnet release.

Install​

npm install @magma-protocol/sdk
# yarn
yarn add @magma-protocol/sdk

# pnpm
pnpm add @magma-protocol/sdk

The SDK is built on the native fetch API and ships with TypeScript declarations. It has no required runtime dependencies. (The optional x402 payments helper dynamically imports x402-fetch only if you use it.)

Instantiate the client​

MagmaClient is the single entry point. The default export and the named export are the same class:

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

const magma = new MagmaClient();

With no options, the client targets the production base URL and behaves as a public, read-only client. No credentials are needed to read narrative feeds, oracle scores, DeFi APYs, leaderboards, or epoch state.

Authenticated client​

Write actions (backing a narrative, viewing personal transaction history, admin operations) require a Privy JWT and the user's Solana wallet address:

const magma = new MagmaClient({
  authToken: privyJwtToken,        // from usePrivy().getAccessToken()
  walletAddress: userWalletAddress // Solana public key
});

When set, the client attaches an Authorization: Bearer <token> header and an X-Wallet-Address header to every request.

Configuration options​

The constructor accepts a MagmaClientOptions object. Every field is optional.

OptionTypeDefaultDescription
baseUrlstringhttps://api.magmaprotocol.xyzAPI base URL. A trailing slash is stripped automatically. Override for local dev or staging.
authTokenstring—Privy JWT. Sent as Authorization: Bearer <token>. Required for write/auth-gated calls.
walletAddressstring—Solana public key. Sent as the X-Wallet-Address header.
timeoutnumber10000Per-request timeout in milliseconds. Backs an AbortController that aborts the in-flight request.
retriesnumber3Maximum auto-retry attempts. Applies to GET requests only (see Error handling).
fetchFetchLikeglobalThis.fetchCustom fetch implementation. Used to inject an x402 payment-wrapped fetch or a polyfill.

FetchLike is a minimal fetch signature, (input, init?) => Promise<Response>, so any spec-compatible fetch (including a payment wrapper) can be supplied:

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

Example: a fully configured client​

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

const magma = new MagmaClient({
  baseUrl: 'http://localhost:3001', // local backend
  authToken: process.env.MAGMA_JWT,
  walletAddress: process.env.MAGMA_WALLET,
  timeout: 15_000,
  retries: 5,
});

Managing the auth lifecycle​

Two helpers let you rotate credentials without re-instantiating the client — handy for Privy token refresh and logout:

// Set/refresh the token (e.g. after a Privy token refresh)
magma.setAuth(newJwt, walletAddress); // walletAddress is optional

// Clear credentials on logout
magma.clearAuth();

setAuth(authToken, walletAddress?) updates the bearer token and, if provided, the wallet address. clearAuth() removes both.

Runtime support​

The SDK is isomorphic and depends only on a global fetch:

RuntimeNotes
BrowserWorks out of the box. fetch is built in.
Node.js 18+fetch is global since Node 18. No polyfill needed.
Edge / serverless (Vercel Edge, Cloudflare Workers)Supported. These runtimes provide a global fetch and AbortController.
React NativeSupported (the runtime provides fetch).
Older Node (< 18)Pass a fetch polyfill via the fetch option.
Module resolution

The package is published with bundler-mode module resolution and is compatible with Next.js, Vite, and Metro. Both ESM and CommonJS consumers are supported.

Next steps​