Tokens

Manage token balances, track rewards, and handle token-related operations through the SolCognia API.

Token Balance

Get Token Balance

Retrieve current token balance and related information:

GET /api/v1/tokens/balance

Response:

{
  "balance": {
    "available": 1250.75,
    "pending": 45.25,
    "staked": 500.00,
    "total": 1796.00
  },
  "currency": "SOL",
  "last_updated": "2024-01-21T10:30:00Z",
  "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Get Balance History

Track balance changes over time:

GET /api/v1/tokens/balance/history?period=30d

Query Parameters:

• period: Time period (1d, 7d, 30d, 90d, 1y)

• limit: Number of records to return (default: 100)

• offset: Number of records to skip (default: 0)

Response:

{
  "history": [
    {
      "date": "2024-01-21",
      "balance": 1250.75,
      "change": +15.25,
      "change_type": "earned"
    },
    {
      "date": "2024-01-20",
      "balance": 1235.50,
      "change": +8.75,
      "change_type": "earned"
    }
  ],
  "summary": {
    "period": "30d",
    "total_earned": 245.50,
    "total_spent": 89.25,
    "net_change": +156.25
  }
}

Token Transactions

List Transactions

Get detailed transaction history:

GET /api/v1/tokens/transactions

Query Parameters:

• type: Filter by transaction type (earned, spent, staked, claimed)

• limit: Number of transactions to return (default: 20)

• offset: Number of transactions to skip (default: 0)

• start_date: Start date for filtering (ISO 8601)

• end_date: End date for filtering (ISO 8601)

Response:

{
  "transactions": [
    {
      "id": "tx_abc123",
      "type": "earned",
      "amount": 15.25,
      "description": "AI model usage rewards",
      "timestamp": "2024-01-21T10:30:00Z",
      "details": {
        "source": "ai_usage",
        "model": "gpt-4",
        "requests": 25,
        "tokens_used": 1525
      },
      "status": "completed"
    },
    {
      "id": "tx_def456",
      "type": "spent",
      "amount": -5.50,
      "description": "Premium AI model access",
      "timestamp": "2024-01-21T09:15:00Z",
      "details": {
        "service": "premium_access",
        "model": "gpt-4-turbo",
        "duration": "1 hour"
      },
      "status": "completed"
    }
  ],
  "total": 2,
  "has_more": false
}

Get Transaction Details

Retrieve detailed information about a specific transaction:

GET /api/v1/tokens/transactions/{transaction_id}

Response:

{
  "id": "tx_abc123",
  "type": "earned",
  "amount": 15.25,
  "description": "AI model usage rewards",
  "timestamp": "2024-01-21T10:30:00Z",
  "status": "completed",
  "blockchain_tx": "5KJp7z8qN3x4mR9vL2wE8fG1hS6tY4uI3oP2nM7kQ9xV",
  "details": {
    "source": "ai_usage",
    "model": "gpt-4",
    "requests": 25,
    "tokens_used": 1525,
    "base_reward": 12.50,
    "bonus_multiplier": 1.22,
    "contribution_score": 750
  }
}

Claiming Rewards

Get Claimable Rewards

Check available rewards that can be claimed:

GET /api/v1/tokens/claimable

Response:

{
  "claimable": {
    "ai_usage": 25.75,
    "referrals": 15.50,
    "community": 8.25,
    "workflows": 12.00,
    "total": 61.50
  },
  "next_claim_available": "2024-01-22T00:00:00Z",
  "minimum_claim_amount": 10.00
}

Claim Rewards

Claim available token rewards:

POST /api/v1/tokens/claim

Request Body:

{
  "amount": 61.50,
  "categories": ["ai_usage", "referrals", "community", "workflows"],
  "wallet_signature": "signature_from_wallet"
}

Response:

{
  "claim_id": "claim_ghi789",
  "amount_claimed": 61.50,
  "transaction_id": "tx_jkl012",
  "status": "processing",
  "estimated_completion": "2024-01-21T10:35:00Z",
  "blockchain_tx": "pending"
}

Get Claim Status

Check the status of a token claim:

GET /api/v1/tokens/claims/{claim_id}

Response:

{
  "claim_id": "claim_ghi789",
  "amount": 61.50,
  "status": "completed",
  "claimed_at": "2024-01-21T10:33:45Z",
  "transaction_id": "tx_jkl012",
  "blockchain_tx": "3mN8pQ5rT7vX2wE9fG4hS1kY6uI8oP3nM2kQ7xV5KJp"
}

Staking

Get Staking Information

View current staking status and available options:

GET /api/v1/tokens/staking

Response:

{
  "current_stake": {
    "amount": 500.00,
    "apy": 8.5,
    "rewards_earned": 15.75,
    "staked_since": "2024-01-01T00:00:00Z"
  },
  "available_pools": [
    {
      "id": "pool_basic",
      "name": "Basic Staking",
      "apy": 6.0,
      "min_stake": 100.00,
      "lock_period": "30d"
    },
    {
      "id": "pool_premium",
      "name": "Premium Staking",
      "apy": 8.5,
      "min_stake": 500.00,
      "lock_period": "90d"
    }
  ]
}

Stake Tokens

Stake tokens in a staking pool:

POST /api/v1/tokens/stake

Request Body:

{
  "pool_id": "pool_premium",
  "amount": 250.00,
  "wallet_signature": "signature_from_wallet"
}

Response:

{
  "stake_id": "stake_mno345",
  "pool_id": "pool_premium",
  "amount": 250.00,
  "apy": 8.5,
  "lock_period": "90d",
  "unlock_date": "2024-04-21T10:30:00Z",
  "status": "active"
}

Unstake Tokens

Withdraw staked tokens (if lock period has ended):

POST /api/v1/tokens/unstake

Request Body:

{
  "stake_id": "stake_mno345",
  "amount": 250.00,
  "wallet_signature": "signature_from_wallet"
}

Reward Analytics

Get Earning Statistics

Analyze token earning patterns:

GET /api/v1/tokens/earnings/stats?period=30d

Response:

{
  "period": "30d",
  "total_earned": 245.50,
  "daily_average": 8.18,
  "breakdown": {
    "ai_usage": 156.75,
    "referrals": 45.25,
    "community": 28.50,
    "workflows": 15.00
  },
  "trends": {
    "growth_rate": 12.5,
    "best_day": {
      "date": "2024-01-15",
      "amount": 25.75
    },
    "contribution_score_impact": 1.35
  }
}

Get Reward Multipliers

View current reward multipliers and how to improve them:

GET /api/v1/tokens/multipliers

Response:

{
  "current_multiplier": 1.35,
  "factors": {
    "contribution_score": {
      "current": 750,
      "multiplier": 1.22,
      "next_tier": 1000,
      "next_multiplier": 1.35
    },
    "staking_bonus": {
      "staked_amount": 500.00,
      "multiplier": 1.10,
      "next_tier": 1000.00,
      "next_multiplier": 1.15
    },
    "loyalty_bonus": {
      "days_active": 45,
      "multiplier": 1.05,
      "next_tier": 90,
      "next_multiplier": 1.10
    }
  },
  "recommendations": [
    "Increase contribution score by participating more in community activities",
    "Stake additional tokens to reach the next staking tier",
    "Maintain daily activity to improve loyalty bonus"
  ]
}

Token Utility

Get Utility Options

View available ways to spend tokens:

GET /api/v1/tokens/utility

Response:

{
  "services": [
    {
      "id": "premium_models",
      "name": "Premium AI Models",
      "description": "Access to advanced AI models",
      "cost": 5.00,
      "unit": "per hour"
    },
    {
      "id": "priority_support",
      "name": "Priority Support",
      "description": "24/7 priority customer support",
      "cost": 25.00,
      "unit": "per month"
    },
    {
      "id": "advanced_workflows",
      "name": "Advanced Workflow Features",
      "description": "Unlock premium workflow capabilities",
      "cost": 15.00,
      "unit": "per month"
    }
  ]
}

Purchase Service

Spend tokens on platform services:

POST /api/v1/tokens/spend

Request Body:

{
  "service_id": "premium_models",
  "duration": "24h",
  "amount": 5.00
}

Response:

{
  "purchase_id": "purchase_pqr678",
  "service_id": "premium_models",
  "amount_spent": 5.00,
  "duration": "24h",
  "expires_at": "2024-01-22T10:30:00Z",
  "status": "active"
}

Error Handling

Insufficient Balance

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient token balance for this operation",
    "required": 100.00,
    "available": 75.50
  }
}

Claim Not Available

{
  "error": {
    "code": "claim_not_available",
    "message": "No claimable rewards available",
    "next_claim_available": "2024-01-22T00:00:00Z"
  }
}

Staking Lock Period

{
  "error": {
    "code": "tokens_locked",
    "message": "Tokens are locked in staking pool",
    "unlock_date": "2024-04-21T10:30:00Z",
    "locked_amount": 500.00
  }
}

The Tokens API will be available with our Q4 2025 developer ecosystem launch.