Version: 1.0.0

MCAP API

This page is the entry-point for the MCAP OpenAPI reference. Use it alongside the task-focused guides for end-to-end flows.

Base URL

• Staging: https://mcap-api-564778804231.us-east4.run.app

Request Authentication

• Provider endpoints: Authorization: Bearer {api_key}
• User (player) endpoints: Authorization: Bearer {jwt_token} obtained via the Auth flow

Amounts and units

All monetary amounts are in wei (base units). Convert human-readable amounts to wei before sending, and convert back when displaying.

Provider vs User

Provider endpoints act on behalf of games and use the Provider API key. User endpoints act on behalf of a signed-in wallet and use a JWT.

Quickstart: Authenticate and create a session

1. Generate a nonce

curl -X POST \
  "$BASE_URL/v1/auth/nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x...",
    "provider_id": "<PROVIDER_ID>"
  }'

2. Sign the nonce with the user's wallet and login

curl -X POST \
  "$BASE_URL/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "<PROVIDER_ID>",
    "wallet_address": "0x...",
    "signature": "0x...",
    "nonce": "..."
  }'

3. Use the access_token for user-secured endpoints, then create a session for a game/token pair

curl -X POST \
  "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "<TOKEN_ID>",
    "game_id": "<GAME_ID>"
  }'

Common API calls

• Search tokens (public)

curl -X POST \
  "$BASE_URL/v1/tokens/search" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": { "include_credit": true },
    "limit": 20
  }'

• Get wallet balances (JWT)

curl -X POST \
  "$BASE_URL/v1/wallets/balance" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "<PROVIDER_ID>",
    "wallet": "0x...",
    "token_ids": ["<TOKEN_ID>"]
  }'

• Create a multiplayer match (JWT)

Note: wager is specified in wei.

curl -X POST \
  "$BASE_URL/v1/user/multiplayer-bets/matches" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_id": "<PLAYER_ID>",
    "max_players": 2,
    "wager": "100000000000000000",
    "game_type": "heads_up",
    "session_id": "<SESSION_ID>",
    "expiry_hours": 1
  }'

Minimal JavaScript example

const BASE_URL = "https://mcap-api-564778804231.us-east4.run.app";

async function generateNonce(providerId, walletAddress) {
  const res = await fetch(`${BASE_URL}/v1/auth/nonce`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ provider_id: providerId, wallet_address: walletAddress })
  });
  return res.json();
}

async function login(providerId, walletAddress, signature, nonce) {
  const res = await fetch(`${BASE_URL}/v1/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ provider_id: providerId, wallet_address: walletAddress, signature, nonce })
  });
  return res.json(); // { access_token, refresh_token, ... }
}

async function createSession(accessToken, tokenId, gameId) {
  const res = await fetch(`${BASE_URL}/v1/sessions`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ token_id: tokenId, game_id: gameId })
  });
  return res.json(); // { session_id }
}

Troubleshooting

• Ensure provider_id is correct and matches your API key/JWT issuer
• Verify Authorization header format: Authorization: Bearer <token>
• Check session validity if calls reference session_id