API Reference

Exchanges a valid Auth1 OTP token for a RevMine access token and refresh token pair.

{
  "auth1_token": "eyJhbGciOiJIUzI1NiIs...",
  "phone": "+15551234567"
}

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_a1b2c3d4e5f6...",
  "expires_in": 86400,
  "user": {
    "id": "usr_abc123",
    "phone": "+15551234567",
    "created_at": "2026-03-01T00:00:00Z"
  }
}

Returns the profile of the currently authenticated user.

{
  "id": "usr_abc123",
  "phone": "+15551234567",
  "email": "user@example.com",
  "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkV",
  "tier": "growth",
  "created_at": "2026-03-01T00:00:00Z"
}

Exchange a valid refresh token for a new access token.

{
  "refresh_token": "rt_a1b2c3d4e5f6..."
}

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 86400
}

Invalidates the current access token and refresh token pair.

{
  "success": true,
  "message": "Logged out successfully"
}

Begins the token creation process. Validates parameters and prepares the on-chain transaction.

{
  "name": "Acme Rewards",
  "symbol": "ACME",
  "total_supply": 1000000,
  "decimals": 8,
  "burn_rate": 5,
  "mining_rate": 6.0,
  "description": "Revenue-backed loyalty token for Acme SaaS",
  "logo_url": "https://example.com/logo.png"
}

{
  "success": true,
  "token_id": "tok_abc123",
  "status": "pending_confirmation",
  "transaction": {
    "unsigned_tx": "base64-encoded-transaction...",
    "expires_at": "2026-03-28T12:05:00Z"
  }
}

Confirms the token creation by submitting the signed transaction. The token is deployed on-chain upon success.

{
  "token_id": "tok_abc123",
  "signed_tx": "base64-encoded-signed-transaction..."
}

{
  "success": true,
  "token_id": "tok_abc123",
  "mint_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkV",
  "tx_signature": "5UfDuYCMPo...",
  "explorer_url": "https://explorer.solana.com/tx/5UfDuYCMPo..."
}

Retrieve details for a specific token including on-chain data.

{
  "id": "tok_abc123",
  "name": "Acme Rewards",
  "symbol": "ACME",
  "mint_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkV",
  "total_supply": 1000000,
  "circulating_supply": 250000,
  "total_burned": 15000,
  "decimals": 8,
  "burn_rate": 5,
  "mining_rate": 6.0,
  "status": "active",
  "created_at": "2026-03-01T00:00:00Z"
}

Returns aggregate statistics for a token: active miners, total mined, burn history, and distribution metrics.

{
  "token_id": "tok_abc123",
  "active_miners": 142,
  "total_mined": 85420.50,
  "total_burned": 15000,
  "total_distributed": 70420.50,
  "burn_count": 12,
  "avg_mining_rate": 6.8,
  "last_burn_at": "2026-03-27T14:30:00Z"
}

Starts a new mining session for the given wallet and token. If an active session already exists, it will be resumed instead.

{
  "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkV",
  "token": "tok_abc123",
  "invitedMiners": 5
}

{
  "success": true,
  "session": {
    "id": "session_1711612800000_a1b2c3d4",
    "miningRate": 9.0,
    "startedAt": "2026-03-28T12:00:00Z",
    "invitedMiners": 5
  }
}

Stops an active mining session. Pending rewards are preserved and can be claimed later.

{
  "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkV",
  "sessionId": "session_1711612800000_a1b2c3d4"
}

{
  "success": true,
  "pendingRewards": 42.75,
  "totalMined": 1250.50
}

Claims accumulated mining rewards. When on-chain distribution is enabled, tokens are transferred to the user's wallet on Solana. Triggers a mining.claimed webhook event.

{
  "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkV",
  "sessionId": "session_1711612800000_a1b2c3d4"
}

{
  "success": true,
  "claimed": 42.75,
  "totalMined": 1293.25,
  "fraudPenalty": null,
  "distribution_status": "on_chain",
  "tx_signature": "5UfDuYCMPo...",
  "distribution_error": null
}

Returns the current mining session status and pending rewards for a wallet.

?wallet=7xKXtg...&token=tok_abc123

{
  "miningActive": true,
  "sessionId": "session_1711612800000_a1b2c3d4",
  "miningRate": 9.0,
  "pendingRewards": 18.50,
  "totalMined": 1250.50,
  "startedAt": "2026-03-28T12:00:00Z",
  "invitedMiners": 5
}

Returns a paginated list of miners for the authenticated user's token.

?token_id=tok_abc123&limit=20&offset=0&status=active

{
  "miners": [
    {
      "id": "miner_7xKXtg..._tok_abc123",
      "wallet": "7xKXtg2CW87d...",
      "tokens_mined": 1250.50,
      "status": "active",
      "joined": "2026-03-01T00:00:00Z",
      "last_active": "2026-03-28T12:00:00Z"
    }
  ],
  "total": 142
}

Returns detailed information for a specific miner by wallet address.

{
  "id": "miner_7xKXtg..._tok_abc123",
  "wallet": "7xKXtg2CW87d...",
  "token_id": "tok_abc123",
  "tokens_mined": 1250.50,
  "status": "active",
  "joined": "2026-03-01T00:00:00Z",
  "last_active": "2026-03-28T12:00:00Z",
  "mining_sessions": 47,
  "total_claims": 32
}

Executes a token distribution to the specified recipients using a configured minting strategy.

{
  "token_id": "tok_abc123",
  "strategy_id": "strat_pro_rata",
  "amount": 10000,
  "note": "March 2026 monthly distribution"
}

{
  "success": true,
  "distribution_id": "dist_abc123",
  "recipients": 142,
  "total_distributed": 10000,
  "tx_signatures": ["5UfDuYCMPo..."],
  "status": "completed"
}

Returns a paginated history of token distributions.

?token_id=tok_abc123&limit=20&offset=0

{
  "distributions": [
    {
      "id": "dist_abc123",
      "token_id": "tok_abc123",
      "amount": 10000,
      "recipients": 142,
      "status": "completed",
      "created_at": "2026-03-28T12:00:00Z"
    }
  ],
  "total": 8
}

Executes an immediate on-chain token burn. Sends tokens to the Solana burn address and records the transaction. Triggers a burn.executed webhook event.

{
  "token_id": "tok_abc123",
  "amount": 5000,
  "note": "Quarterly deflationary burn",
  "dry_run": false
}

{
  "message": "Burn executed successfully",
  "burn": {
    "id": "burn_1711612800000_a1b2c3d4e",
    "token_id": "tok_abc123",
    "amount": 5000,
    "status": "completed",
    "executed_at": "2026-03-28T12:00:00Z",
    "tx_signature": "5UfDuYCMPo..."
  },
  "transaction": {
    "signature": "5UfDuYCMPo...",
    "explorer_url": "https://explorer.solana.com/tx/5UfDuYCMPo..."
  }
}

Returns a paginated list of past burn events.

?token_id=tok_abc123&limit=20&offset=0

{
  "burns": [
    {
      "id": "burn_1711612800000_a1b2c3d4e",
      "token_id": "tok_abc123",
      "amount": 5000,
      "status": "completed",
      "trigger_type": "manual",
      "tx_signature": "5UfDuYCMPo...",
      "executed_at": "2026-03-28T12:00:00Z"
    }
  ],
  "total": 12
}

Performs a dry-run burn simulation. No tokens are actually burned. Returns projected supply impact.

{
  "token_id": "tok_abc123",
  "amount": 5000
}

{
  "simulation": true,
  "token_id": "tok_abc123",
  "burn_amount": 5000,
  "current_supply": 985000,
  "projected_supply": 980000,
  "supply_reduction_pct": 0.51,
  "estimated_tx_fee": 0.000005
}

Returns the list of achievements and the user's progress toward each.

{
  "achievements": [
    {
      "id": "ach_first_mine",
      "name": "First Mine",
      "description": "Complete your first mining session",
      "reward": 50,
      "completed": true,
      "completed_at": "2026-03-02T10:00:00Z"
    },
    {
      "id": "ach_100_tokens",
      "name": "Century Miner",
      "description": "Mine 100 tokens",
      "reward": 200,
      "completed": false,
      "progress": 72,
      "target": 100
    }
  ]
}

Returns currently active time-limited challenges.

{
  "challenges": [
    {
      "id": "chl_march_sprint",
      "name": "March Mining Sprint",
      "description": "Mine 500 tokens before March 31",
      "reward": 1000,
      "progress": 320,
      "target": 500,
      "ends_at": "2026-03-31T23:59:59Z"
    }
  ]
}

Returns the top miners ranked by total tokens mined.

?token_id=tok_abc123&limit=50

{
  "leaderboard": [
    {
      "rank": 1,
      "wallet": "7xKX...gHkV",
      "tokens_mined": 12500.00,
      "tier": "Diamond"
    }
  ]
}

Returns aggregate referral statistics including conversion rate, rewards paid, and tier breakdown.

{
  "total_referrals": 245,
  "confirmed_referrals": 189,
  "pending_referrals": 56,
  "conversion_rate": 77.1,
  "total_rewards_paid": 18900,
  "avg_reward_per_referral": 100,
  "tiers": [
    {
      "name": "Starter",
      "minReferrals": 0,
      "reward": 50
    },
    {
      "name": "Gold",
      "minReferrals": 10,
      "reward": 100
    }
  ]
}

Returns the authenticated user's referral codes and their usage stats.

{
  "codes": [
    {
      "code": "ACME-JOHN-2026",
      "uses": 12,
      "max_uses": 100,
      "reward_per_use": 100,
      "created_at": "2026-03-01T00:00:00Z"
    }
  ]
}

Registers a new webhook URL to receive event notifications. The URL must be publicly accessible and must not target private IP ranges. An HMAC signing secret is generated automatically if not provided.

{
  "url": "https://example.com/webhooks/revmine",
  "events": [
    "mining.claimed",
    "burn.executed",
    "referral.confirmed"
  ],
  "secret": "optional-custom-secret"
}

{
  "id": "wh_1711612800000_a1b2c3d4e5f6",
  "url": "https://example.com/webhooks/revmine",
  "events": ["mining.claimed", "burn.executed", "referral.confirmed"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "created_at": "2026-03-28T12:00:00Z"
}

Returns all registered webhooks for the authenticated user. Secrets are masked (only last 8 characters shown).

{
  "webhooks": [
    {
      "id": "wh_1711612800000_a1b2c3d4e5f6",
      "url": "https://example.com/webhooks/revmine",
      "events": ["mining.claimed", "burn.executed"],
      "active": true,
      "secret_hint": "...d4e5f6a7",
      "created_at": "2026-03-28T12:00:00Z"
    }
  ],
  "total": 1
}

Permanently deletes a webhook registration. Events will no longer be delivered to this URL.

{
  "success": true,
  "id": "wh_1711612800000_a1b2c3d4e5f6",
  "message": "Webhook deleted"
}

Returns the current widget configuration for the authenticated user's token.

{
  "token_id": "tok_abc123",
  "theme": "dark",
  "position": "bottom-right",
  "color": "#f97316",
  "show_leaderboard": true,
  "show_referral": true,
  "custom_css": null
}

Updates the widget configuration. All fields are optional; only provided fields are updated.

{
  "theme": "dark",
  "position": "bottom-right",
  "color": "#f97316",
  "show_leaderboard": true,
  "show_referral": true
}

{
  "success": true,
  "message": "Widget configuration updated"
}

Generates the HTML embed snippet for the mining widget.

{
  "token_id": "tok_abc123"
}

{
  "embed_code": "<script src=\"https://revmine.ai/widget.js\" data-token=\"tok_abc123\"></script>",
  "widget_key": "wk_abc123"
}