Getting Started
This page takes you from zero to a working request against the MAGMA API, then to the same call through the TypeScript SDK.
1. Base URL
All REST endpoints are served under a single base URL:
https://api.magmaprotocol.xyz
Versioned routes live under /v1. A small number of operational routes (health,
admin) sit at the root. See the API Reference for the full map.
2. A first unauthenticated call
Most read endpoints (narrative feed, conviction data, DeFi APYs) are public and rate-limited by IP. Try the live narrative feed:
curl -s https://api.magmaprotocol.xyz/v1/narratives | jq '.narratives[0]'
You'll get back the most recent narratives with their conviction and oracle metadata. No key required.
3. Authentication
Write actions (backing a narrative, preparing a mint) are authorized by the user's Solana wallet — the transaction itself is signed client-side and the signature is submitted alongside the request. Privileged/admin endpoints use wallet header credentials. The details, including which routes need which, are in Authentication.
# Example: read a wallet's backings (public, by wallet)
curl -s https://api.magmaprotocol.xyz/v1/users/<WALLET>/backings | jq
4. Install the SDK
The TypeScript SDK wraps every resource with full types and handles base URLs, retries, and pagination for you.
npm install @magma-protocol/sdk
import { MagmaClient } from '@magma-protocol/sdk';
const magma = new MagmaClient({
// baseUrl defaults to https://api.magmaprotocol.xyz
});
// Same call as above, fully typed
const feed = await magma.narratives.feed({ limit: 20 });
console.log(feed.narratives.length);
See SDK · Installation and the TypeScript client reference for every resource.
5. Submitting a backing
Backing a narrative is a two-step flow: build and sign the Solana transaction with the user's wallet, then submit the signature to the API so MAGMA can record the position and route principal into yield.
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, result.yield);
The SDK only retries idempotent GET requests. Backing, minting, and challenge
calls never auto-retry, so a network blip can't double-submit a transaction.
6. Machine-payable endpoints (x402)
Select premium/data endpoints support x402 — an HTTP-native, pay-per-call settlement standard ideal for agents and automated consumers. The SDK can wrap any client with an x402-capable wallet so payments are negotiated transparently. See x402 Payments.