Skip to main content

Getting Started with MCAP

About MCAP​

MCAP is a gaming infrastructure platform that bridges on-chain assets and off-chain gameplay, enabling real-money mechanics with instant UX.

What MCAP Enables​

  • Off-Chain Balance Management: Users deposit ERC20 tokens into provider vaults; MCAP mirrors balances off-chain for instant, gas-free gameplay.
  • Session Management: Secure, temporary sessions binding user, token, and game.
  • Complete Gaming Stack: Bets, leaderboards, credit tokens, and real-time settlement.

Integration Overview​

  1. Register as a provider; receive Provider ID, API key, and Vault address.
  2. Let users connect a wallet (EVM or Flow EVM).
  3. Build deposit UI to your provider Vault.
  4. Implement auth: nonce → wallet signature → JWT.
  5. Create a session for the selected token and your game.
  6. Place bets and settle outcomes via provider endpoints.

Environment & Auth​

  • Base URL (staging): https://mcap-api-564778804231.us-east4.run.app
  • Provider endpoints: Authorization: Bearer {api_key}
  • User endpoints: Authorization: Bearer {jwt_token}
  • Amounts are in wei (base units).

Step 1 — Provider Setup​

Contact the MCAP team to obtain:

  • Provider ID
  • API key (server-to-server)
  • Provider Vault contract address

Use the API key only on your backend.

Step 2 — Wallet Connection​

Let users connect MetaMask (EVM) or Flow EVM wallets. Store the address client-side; never expose provider API keys.

Step 3 — Deposits to Vault​

Users deposit supported ERC20 tokens to your provider’s Vault. MCAP detects deposits on-chain and updates off-chain balances automatically.

High-level EVM flow:

// Pseudocode (Ethers/Web3)
await erc20.approve(vaultAddress, amount);
await vault.deposit(tokenAddress, amount);
// Wait a block or two; MCAP will reflect balance in API

Step 4 — Authentication (JWT)​

  1. Request a nonce for the wallet.
  2. User signs the nonce.
  3. Backend verifies with MCAP and returns a JWT.
POST /v1/auth/nonce
POST /v1/auth/login
GET  /v1/auth/profile

Store the JWT securely (httpOnly cookie or secure storage) and attach to user endpoints.

Step 5 — Create a Session​

Create a session linking wallet + token + game. Use the user’s JWT.

POST /v1/sessions
{
  "token_id": "<UUID>",
  "game_id": "<UUID>"
}

Provider backends can fetch session details with the API key:

GET /v1/providers/sessions/{session_id}

Step 6 — Game Flows​

Player vs Server (Single Player)​

  1. Place bet (locks funds), then submit outcome to settle.
POST /v1/providers/bets/place-bet
POST /v1/providers/bets/bet-outcome

Head‑to‑Head (Multiplayer)​

Create/join matches with the user JWT; provider starts/settles with API key.

POST   /v1/user/multiplayer-bets/matches
POST   /v1/user/multiplayer-bets/matches/{match_id}/join
POST   /v1/providers/multiplayer-bets/matches/{match_id}/start
POST   /v1/providers/multiplayer-bets/matches/{match_id}/settle

Reference: Common Endpoints​

  • Sessions: POST /v1/sessions, GET /v1/providers/sessions/{id}
  • Auth: POST /v1/auth/nonce, POST /v1/auth/login, GET /v1/auth/profile
  • Bets (provider): POST /v1/providers/bets/place-bet, POST /v1/providers/bets/bet-outcome
  • Multiplayer: POST /v1/user/multiplayer-bets/matches
  • Wallets: POST /v1/wallets/balance, POST /v1/wallets/withdraw
  • Tokens: POST /v1/tokens/search

Quick Start Checklist​

  • Provider ID, API key, Vault address
  • Wallet connect (EVM/Flow EVM)
  • Deposit UI to Vault
  • Auth flow (nonce → sign → JWT)
  • Session creation
  • Implement bet lifecycle

Support​

Use the API as above; format token amounts from wei; contact the MCAP team for access and questions.