Developers

Vulcasino API & SDK

A public, versioned REST API for the catalog, provably-fair verification, and API-key management — plus a dependency-free TypeScript SDK. Money-moving actions (bets, deposits, withdrawals, claims) are intentionally not in the public API; they stay behind an authenticated session.

https://api.vulcasino.magmaprotocol.xyzv1

Authentication & rate limits

Read endpoints are open and metered by IP; an API key raises your limit. Send it asX-API-Key: vk_… (or Authorization: Bearer vk_…). Every response carries X-RateLimit-* headers.

Endpoints

Provably-fair verification

Every Originals outcome is reproducible from its published random word — the endpoint runs the exact same math as the server and the on-chain contracts.

curl -s https://api.vulcasino.magmaprotocol.xyz/v1/provably-fair/originals \
  -H 'content-type: application/json' \
  -d '{"game":"dice","word":"123456789012345678901234567890",
       "params":{"target":5000,"direction":"under"}}'

# → { "game":"dice", "word":"…", "outcome":{ "payoutMilli":…, "win":…, "detail":{…} } }

TypeScript SDK

@vulcasino/sdk is a zero-dependency client for the browser and Node 18+.

npm install @vulcasino/sdk

import { VulcasinoClient } from '@vulcasino/sdk';

const vc = new VulcasinoClient({
  apiKey: process.env.VULCASINO_API_KEY, // optional — raises your rate limit
});

const { outcome } = await vc.verifyOriginal({
  game: 'dice',
  word: '123456789012345678901234567890',
  params: { target: 5000, direction: 'under' },
});

console.log(outcome.win, outcome.payoutMilli);

Managing keys

Keys are minted with your signed-in session bearer and are owner-scoped. The secret is shown exactly once — store it immediately. Agents that need pay-per-use access top up an agent key (see the x402 metering layer).

const vc = new VulcasinoClient({ sessionToken });
const { key } = await vc.keys.create({ label: 'my bot', tier: 'agent' });
// store `key` (vk_…) now — it is never shown again
await vc.keys.list();
await vc.keys.revoke(id);

x402 — pay-per-use for agents

Agents fund an agent key with prepaid request credits over thex402HTTP-402 handshake — no human checkout. Discover the price at GET /v1/x402/pricing, then top up:

1. 1. POST the top-up with no payment → 402 with an accepts array — one entry per settlement rail (Base/EVM + Solana/SVM). Pay on whichever chain you hold USDC on.
2. 2. Sign the payment with your wallet (or an x402 client lib) and base64-encode it.
3. 3. Retry with an X-PAYMENT header — the server settles and grants the credits; the receipt returns in X-PAYMENT-RESPONSE.

// with @vulcasino/sdk
const vc = new VulcasinoClient({ sessionToken });

try {
  await vc.keys.topup(keyId, { credits: 10_000 });
} catch (e) {
  // e.status === 402 — e.body.accepts lists a requirement per rail (Base + Solana)
  const req = e.body.accepts.find((a) => a.network === myNetwork) ?? e.body.accepts[0];
  const paymentHeader = await buildX402Payment(req); // your wallet / x402 lib
  const { credits } = await vc.keys.topup(keyId, { credits: 10_000, paymentHeader });
  // → credits now reflects the top-up
}

Settlements are recorded once (idempotent by settlement id), so a replayed payment never double-credits. Set the facilitator to remote to settle on-chain via a real x402 facilitator.

The public API is read + verify + keys only. It never exposes wagering, funds movement, or personal data.