Skip to main content

id: api

API Reference

Overview​

TON Arcana provides both GraphQL and REST APIs for interacting with the platform. The APIs are secured with Basic Authentication and require proper credentials.

GraphQL API​

Endpoint​

https://api.arcana.monster/graphql

Authentication​

Authorization: Basic <credentials>

Queries​

Get User Balance​

query GetBalance($userId: Int!) {
  balance(userId: $userId) {
    available
    total
    pending
  }
}

Get Reading History​

query GetReadings($userId: Int!, $limit: Int = 10) {
  readings(userId: $userId, limit: $limit) {
    id
    type
    cards
    interpretation
    createdAt
  }
}

Mutations​

Request Reading​

mutation RequestReading($input: ReadingInput!) {
  requestReading(input: $input) {
    id
    status
    estimatedTime
  }
}

Transfer Tokens​

mutation TransferTokens($input: TransferInput!) {
  transferTokens(input: $input) {
    txHash
    status
  }
}

REST API​

Base URL​

https://api.arcana.monster

Authentication​

Authorization: Basic <credentials>

Endpoints​

Health Check​

GET /health

Webhook Handler​

POST /telegram/webhook

WebSocket API​

Connection​

wss://api.arcana.monster/events

Events​

Reading Updates​

interface ReadingUpdate {
  type: 'reading_update';
  data: {
    id: string;
    status: 'pending' | 'completed' | 'failed';
    result?: ReadingResult;
  };
}

Balance Updates​

interface BalanceUpdate {
  type: 'balance_update';
  data: {
    userId: number;
    newBalance: number;
    txHash?: string;
  };
}

NEXT_TASK: Implement WebSocket API for real-time reading and balance updates with proper event handling

Error Handling​

Error Codes​

  • AUTH_001: Authentication failed
  • BAL_001: Insufficient balance
  • READ_001: Reading generation failed
  • TOK_001: Token transfer failed

Error Response Format​

interface ErrorResponse {
  code: string;
  message: string;
  details?: Record<string, any>;
}

Rate Limiting​

  • 100 requests per minute per IP
  • 1000 requests per hour per user
  • Webhook endpoints have separate limits

Development Tools​

API Explorer​

  • GraphQL Playground: /graphql
  • Swagger UI: /docs
  • ReDoc: /redoc

Testing​

  • Test environment: https://test-api.arcana.monster
  • Test credentials available on request
  • Sandbox mode for blockchain operations