Vault System

The Vault system provides businesses with deterministic deposit addresses for their users. Each user gets a unique address that accepts any enabled token, with automatic processing and webhook notifications.

Overview

Key Features:

One Address Per User - Each user gets a single deposit address that accepts ANY enabled token
Deterministic Addresses - Addresses are computed using CREATE2, same across all supported chains
Permissionless - No on-chain registration required, works immediately
Automatic Processing - Deposits are detected and processed automatically
Webhook Notifications - Real-time notifications when deposits are processed
Low Fees - 0.25% default fee on all deposits

How It Works

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Flow                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Business creates user     2. User deposits tokens            │
│     via API/Dashboard            to their address                │
│           │                           │                          │
│           ▼                           ▼                          │
│  ┌─────────────────┐         ┌─────────────────┐                │
│  │ MakaPay Backend │         │ Deposit Address │                │
│  │ computeAddress()│         │  (CREATE2)      │                │
│  └────────┬────────┘         └────────┬────────┘                │
│           │                           │                          │
│           ▼                           ▼                          │
│  ┌─────────────────┐         ┌─────────────────┐                │
│  │ Deposit Address │         │ Deposit Detected│                │
│  │ returned to     │         │ by cron job     │                │
│  │ business        │         └────────┬────────┘                │
│  └─────────────────┘                  │                          │
│                                       ▼                          │
│                              ┌─────────────────┐                │
│  3. Funds swept to           │ Factory.process()│                │
│     business wallet          │ sweeps funds    │                │
│           ▲                  └────────┬────────┘                │
│           │                           │                          │
│           └───────────────────────────┘                          │
│                                                                  │
│  4. Webhook sent to business with deposit details                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Address Computation

Deposit addresses are deterministic using CREATE2:

salt = keccak256(userId, casinoAddress)
address = CREATE2(factory, salt, walletBytecode)

Important: The same userId + casinoAddress combination always produces the same deposit address, regardless of which token is being deposited.

Smart Contracts

Contract Addresses

Contract

Address

Networks

Factory

0xDEBd5F39a53e86DC1887eaf9eBc9B8a8E635bEA2

Sepolia, MakaChain Testnet

Implementation

0x74260BBA1dD0a990Eef6950f58D2eC14f14403e1

Sepolia, MakaChain Testnet

Factory Functions

`computeAddress(string userId, address casino)`

Computes the deterministic deposit address for a user.

function computeAddress(
    string calldata userId,
    address casino
) external view returns (address)

Parameters:

userId - Your internal user identifier (e.g., "user_123", "player_abc")
casino - Your business wallet address (where funds are sent after processing)

Returns: The deposit address for this user

`process(string userId, address casino, address token, bytes callbackData)`

Processes a deposit by sweeping funds from the deposit address to the casino wallet.

function process(
    string calldata userId,
    address casino,
    address token,
    bytes calldata callbackData
) external returns (address wallet, uint256 amount, uint256 fee)

Parameters:

userId - The user's identifier
casino - Your business wallet address
token - The token contract address being processed
callbackData - Optional data passed to your callback (usually the userId encoded)

Returns:

wallet - The deposit wallet address
amount - Total amount processed (before fee)
fee - Fee amount deducted

Fee Structure

Type

Fee

Recipient

Default (unregistered)

0.25% (25 bps)

MakaPay Treasury

Registered Casino

Custom (0-1%)

Custom recipient

Fees are automatically deducted during the process() call:

Fee is sent to the fee recipient
Remaining funds are sent to the casino wallet

Dashboard Setup

1. Configure Your Vault

Navigate to Dashboard > Vault > Settings:

Business Name - Your business display name
Wallet Address - Where processed funds are sent
Enabled Tokens - Select which tokens to accept (USDT, USDC, etc.)

2. Create User Addresses

Navigate to Dashboard > Vault > Users:

Click Create User
Enter the User ID (your internal identifier)
The deposit address is generated automatically

3. Configure Webhooks (Optional)

Navigate to Dashboard > Vault > Settings > Webhooks:

Enter your Webhook URL
Add a Webhook Secret for signature verification
Select which events to receive

API Integration

Authentication

All API endpoints require an API key in the x-api-key header:

curl -X GET "https://api.makapay.com/api/vault/v1/config" \
  -H "x-api-key: your_api_key"

Endpoints

Get Vault Configuration

GET /api/vault/v1/config

Response:

{
  "success": true,
  "data": {
    "publicId": "biz_abc123",
    "businessName": "My Casino",
    "walletAddress": "0x...",
    "feeBps": 25,
    "isActive": true,
    "enabledTokens": [
      {
        "chainId": 11155111,
        "tokenSymbol": "USDT",
        "tokenAddress": "0x..."
      }
    ]
  }
}

Create User / Get Deposit Address

POST /api/vault/v1/users
Content-Type: application/json

{
  "externalUserId": "user_123",
  "chainId": 11155111,
  "tokenAddress": "0x..."
}

Response:

{
  "success": true,
  "data": {
    "depositAddress": "0x...",
    "externalUserId": "user_123",
    "chainId": 11155111,
    "tokenSymbol": "USDT",
    "isNew": true
  }
}

Get User Info

GET /api/vault/v1/users?externalUserId=user_123

Response:

{
  "success": true,
  "data": {
    "externalUserId": "user_123",
    "depositAddress": "0x...",
    "chainId": 11155111,
    "tokenSymbol": "USDT",
    "totalDeposited": "1000000000",
    "depositCount": 5,
    "lastDepositAt": 1704067200000
  }
}

List Deposits

GET /api/vault/v1/deposits?limit=50&status=completed

Query Parameters:

limit - Max results (default: 50, max: 100)
status - Filter by status: detected, processing, completed, failed
externalUserId - Filter by user

Response:

{
  "success": true,
  "data": {
    "deposits": [
      {
        "depositId": "abc123",
        "externalUserId": "user_123",
        "amount": "1000000",
        "fee": "2500",
        "netAmount": "997500",
        "chainId": 11155111,
        "tokenSymbol": "USDT",
        "status": "completed",
        "depositTxHash": "0x...",
        "processTxHash": "0x...",
        "createdAt": 1704067200000,
        "processedAt": 1704067260000
      }
    ],
    "total": 1
  }
}

Get Supported Tokens (Public)

GET /api/vault/v1/business/{publicId}/tokens

No authentication required. Returns publicly available token information.

Response:

{
  "tokens": [
    {
      "chainId": 11155111,
      "symbol": "USDT",
      "address": "0x..."
    },
    {
      "chainId": 11155111,
      "symbol": "USDC",
      "address": "0x..."
    }
  ]
}

Webhooks

Webhook Events

Event

Description

deposit.completed

Deposit successfully processed

deposit.failed

Deposit processing failed

deposit.*

All deposit events

Webhook Payload

{
  "event": "deposit.completed",
  "data": {
    "depositId": "abc123",
    "externalUserId": "user_123",
    "amount": "1000000",
    "fee": "2500",
    "netAmount": "997500",
    "tokenSymbol": "USDT",
    "tokenAddress": "0x...",
    "chainId": 11155111,
    "depositAddress": "0x...",
    "status": "completed",
    "depositTxHash": "0x...",
    "processTxHash": "0x...",
    "timestamp": 1704067260000
  },
  "timestamp": 1704067260000
}

Webhook Signature Verification

If you configure a webhook secret, requests include an X-Webhook-Signature header:

X-Webhook-Signature: sha256(JSON.stringify(payload) + secret)

Verification Example (Node.js):

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHash('sha256')
    .update(JSON.stringify(payload) + secret)
    .digest('hex');
  return signature === expected;
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook...
  const { event, data } = req.body;

  if (event === 'deposit.completed') {
    // Credit user's balance
    await creditUserBalance(data.externalUserId, data.netAmount);
  }

  res.json({ received: true });
});

Integration Examples

Computing Address On-Chain (Solidity)

interface ICasinoWalletFactory {
    function computeAddress(
        string calldata userId,
        address casino
    ) external view returns (address);
}

contract MyIntegration {
    ICasinoWalletFactory public factory =
        ICasinoWalletFactory(0xDEBd5F39a53e86DC1887eaf9eBc9B8a8E635bEA2);

    function getDepositAddress(string calldata userId) external view returns (address) {
        return factory.computeAddress(userId, address(this));
    }
}

Computing Address Off-Chain (JavaScript)

import { createPublicClient, http } from 'viem';
import { sepolia } from 'viem/chains';

const FACTORY_ADDRESS = '0xDEBd5F39a53e86DC1887eaf9eBc9B8a8E635bEA2';
const FACTORY_ABI = [
  {
    inputs: [
      { name: 'userId', type: 'string' },
      { name: 'casino', type: 'address' }
    ],
    name: 'computeAddress',
    outputs: [{ name: '', type: 'address' }],
    stateMutability: 'view',
    type: 'function'
  }
];

const client = createPublicClient({
  chain: sepolia,
  transport: http()
});

async function getDepositAddress(userId, casinoAddress) {
  const address = await client.readContract({
    address: FACTORY_ADDRESS,
    abi: FACTORY_ABI,
    functionName: 'computeAddress',
    args: [userId, casinoAddress]
  });
  return address;
}

// Usage
const depositAddress = await getDepositAddress('user_123', '0xYourWallet...');
console.log('Deposit to:', depositAddress);

Full Integration Flow

// 1. Create user and get deposit address
const response = await fetch('https://api.makapay.com/api/vault/v1/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.MAKAPAY_API_KEY
  },
  body: JSON.stringify({
    externalUserId: 'user_123',
    chainId: 11155111,
    tokenAddress: '0x...' // USDT address
  })
});

const { data } = await response.json();
const depositAddress = data.depositAddress;

// 2. Show address to user (they send tokens here)
console.log('Send USDT to:', depositAddress);

// 3. Handle webhook when deposit is processed
app.post('/webhooks/makapay', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.completed') {
    // Credit user in your system
    await db.users.update({
      where: { externalId: data.externalUserId },
      data: {
        balance: { increment: BigInt(data.netAmount) }
      }
    });

    console.log(`Credited ${data.netAmount} to user ${data.externalUserId}`);
  }

  res.json({ received: true });
});

Supported Networks

Network

Chain ID

Status

Sepolia Testnet

11155111

Active

MakaChain Testnet

777177

Active

MakaChain Mainnet

777178

Coming Soon

Ethereum Mainnet

Coming Soon

Polygon

137

Coming Soon

BSC

Coming Soon

Deposit Statuses

Status

Description

detected

Deposit detected, awaiting processing

processing

Currently being processed on-chain

completed

Successfully processed, funds sent to wallet

failed

Processing failed (will retry automatically)

Best Practices

User ID Guidelines

Use unique, stable identifiers (database IDs, UUIDs)
Don't use email addresses (may change)
Don't use session tokens (temporary)
Keep IDs under 100 characters

Security

Store API keys securely - Use environment variables, never commit to code
Verify webhook signatures - Always validate the X-Webhook-Signature header
Use HTTPS - All webhook endpoints must use HTTPS
Idempotency - Handle duplicate webhook deliveries gracefully

Error Handling

Check deposit status - Poll the deposits endpoint if webhooks fail
Retry logic - Failed deposits are automatically retried
Monitor failed deposits - Set up alerts for repeated failures

Troubleshooting

Deposit Not Detected

Verify the correct deposit address was used
Check the token is in the enabled tokens list
Ensure minimum deposit amount (> 0.001 tokens)
Wait for block confirmations

Webhook Not Received

Verify webhook URL is accessible from the internet
Check webhook is enabled and active
Ensure the event type is selected
Check your server logs for incoming requests

Process Transaction Failed

Check the casino wallet address is correct
Verify sufficient gas on the processing account
Check the token contract is valid
Review error message in the deposit record

Rate Limits

Endpoint

Limit

Create User

100/min

Get User

1000/min

List Deposits

100/min

Get Config

100/min

Support

Documentation: docs.makapay.com
GitHub Issues: github.com/makapay/issues
Email: [email protected]

PreviousToken Recovery NextGas Tank

Last updated 18 days ago

Good morning

hashtagOverview

hashtagHow It Works

hashtagArchitecture

hashtagAddress Computation

hashtagSmart Contracts

hashtagContract Addresses

hashtagFactory Functions

hashtagcomputeAddress(string userId, address casino)

hashtagprocess(string userId, address casino, address token, bytes callbackData)

hashtagFee Structure

hashtagDashboard Setup

hashtag1. Configure Your Vault

hashtag2. Create User Addresses

hashtag3. Configure Webhooks (Optional)

hashtagAPI Integration

hashtagAuthentication

hashtagEndpoints

hashtagGet Vault Configuration

hashtagCreate User / Get Deposit Address

hashtagGet User Info

hashtagList Deposits

hashtagGet Supported Tokens (Public)

hashtagWebhooks

hashtagWebhook Events

hashtagWebhook Payload

hashtagWebhook Signature Verification

hashtagIntegration Examples

hashtagComputing Address On-Chain (Solidity)

hashtagComputing Address Off-Chain (JavaScript)

hashtagFull Integration Flow

hashtagSupported Networks

hashtagDeposit Statuses

hashtagBest Practices

hashtagUser ID Guidelines

hashtagSecurity

hashtagError Handling

hashtagTroubleshooting

hashtagDeposit Not Detected

hashtagWebhook Not Received

hashtagProcess Transaction Failed

hashtagRate Limits

hashtagSupport

Overview

How It Works

Architecture

Address Computation

Smart Contracts

Contract Addresses

Factory Functions

`computeAddress(string userId, address casino)`

`process(string userId, address casino, address token, bytes callbackData)`

Fee Structure

Dashboard Setup

1. Configure Your Vault

2. Create User Addresses

3. Configure Webhooks (Optional)

API Integration

Authentication

Endpoints

Get Vault Configuration

Create User / Get Deposit Address

Get User Info

List Deposits

Get Supported Tokens (Public)

Webhooks

Webhook Events

Webhook Payload

Webhook Signature Verification

Integration Examples

Computing Address On-Chain (Solidity)

Computing Address Off-Chain (JavaScript)

Full Integration Flow

Supported Networks

Deposit Statuses

Best Practices

User ID Guidelines

Security

Error Handling

Troubleshooting

Deposit Not Detected

Webhook Not Received

Process Transaction Failed

Rate Limits

Support