> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odin.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Comprehensive API for the Odin crypto trading platform with token management, trade viewing, and social features

# Odin API Documentation

Welcome to the Odin API documentation. Odin is a crypto trading platform built on Bitcoin infrastructure, featuring token discovery, trade viewing, social interactions, and user management.

## Platform Overview

<CardGroup cols={2}>
  <Card title="Token Management" icon="coins" href="/api-reference/tokens/get-tokens">
    Create, manage, and discover tokens with comprehensive metadata and social features.
  </Card>

  <Card title="Trade Data" icon="chart-line" href="/api-reference/trades/get-trades">
    View trade history and market data with detailed filtering options.
  </Card>

  <Card title="Social Features" icon="comments" href="/api-reference/tokens/post-token-comment">
    Community comments, favorites, and social engagement around tokens.
  </Card>

  <Card title="User Management" icon="user" href="/api-reference/users/get-users">
    User profiles, balances, activity tracking, and achievements.
  </Card>
</CardGroup>

## API Architecture

The Odin API follows RESTful principles:

<Tabs>
  <Tab title="REST Endpoints">
    Standard HTTP methods for operations:

    * `GET` for data retrieval (most endpoints)
    * `POST` for creating resources (some endpoints)
    * `PATCH` for partial updates (limited endpoints)
    * `DELETE` for resource removal (limited endpoints)
  </Tab>

  <Tab title="Authentication">
    Most endpoints are public and don't require authentication. JWT authentication is only required for:

    * Creating or modifying user-owned resources
    * Accessing private user data
    * Administrative actions
    * Specific protected endpoints
  </Tab>

  <Tab title="Data Format">
    JSON API responses with:

    * Consistent response structure
    * Pagination for large datasets
    * Error handling with descriptive messages
    * Standardized field naming
  </Tab>
</Tabs>

## Getting Started

<Steps>
  <Step title="Explore Public Data">
    Start by exploring tokens and market data without authentication.

    ```bash theme={null}
    # Get list of tokens
    curl -X GET 'https://api.odin.fun/v1/tokens?limit=10'

    # View trade history
    curl -X GET 'https://api.odin.fun/v1/trades?limit=10'

    # Search across platform
    curl -X GET 'https://api.odin.fun/v1/search?q=bitcoin'
    ```

    <Tip>
      Most endpoints don't require authentication and can be accessed immediately.
    </Tip>
  </Step>

  <Step title="Authentication Setup (Optional)">
    Set up authentication only if you need to access protected endpoints or user-specific data.

    Follow our detailed getting started guide: [Quickstart Guide](/quickstart/quickstart-04-canister-calls)

    <CodeGroup>
      ```javascript Node.js theme={null}
      const authRequest = {
        publickey: "your_public_key",
        delegation: "your_delegation",
        timestamp: Date.now().toString(),
        signature: "your_signature"
      };

      const response = await fetch('https://api.odin.fun/v1/auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(authRequest)
      });

      const { token } = await response.json();
      ```

      ```python Python theme={null}
      import requests
      import time

      auth_data = {
          "publickey": "your_public_key",
          "delegation": "your_delegation", 
          "timestamp": str(int(time.time() * 1000)),
          "signature": "your_signature"
      }

      response = requests.post(
          'https://api.odin.fun/v1/auth',
          json=auth_data
      )

      token = response.json()['token']
      ```

      ```curl cURL theme={null}
      curl -X POST 'https://api.odin.fun/v1/auth' \
        -H 'Content-Type: application/json' \
        -d '{
          "publickey": "your_public_key",
          "delegation": "your_delegation",
          "timestamp": "1640995200000",
          "signature": "your_signature"
        }'
      ```
    </CodeGroup>

    <Check>
      Save the returned JWT token for subsequent authenticated API calls.
    </Check>
  </Step>

  <Step title="Access Protected Endpoints">
    Use authentication to access protected endpoints that require JWT tokens.

    ```bash theme={null}
    # Create a new tag (requires auth)
    curl -X POST 'https://api.odin.fun/v1/tags' \
      -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{"name": "meme", "description": "Meme tokens"}'

    # Claim an achievement (requires auth)
    curl -X POST 'https://api.odin.fun/v1/user/achievement/1/claim' \
      -H 'Authorization: Bearer YOUR_JWT_TOKEN'
    ```

    <Warning>
      Only specific endpoints require authentication - most data viewing endpoints are public.
    </Warning>
  </Step>
</Steps>

## Response Format

All API responses follow a consistent structure:

<Tabs>
  <Tab title="Success Response">
    ```json theme={null}
    {
      "data": [...], // Response data
      "count": 25,   // Total count (for paginated responses)
      "page": 1,     // Current page
      "limit": 10    // Items per page
    }
    ```
  </Tab>

  <Tab title="Error Response">
    ```json theme={null}
    {
      "error": "Bad Request",
      "message": "Invalid parameter: limit must be between 1 and 100",
      "statusCode": 400
    }
    ```
  </Tab>

  <Tab title="Single Item">
    ```json theme={null}
    {
      "data": {
        "id": "btc",
        "name": "Bitcoin",
        "price": 50000
      }
    }
    ```
  </Tab>
</Tabs>

## Base URL

<CodeGroup>
  ```bash Production theme={null}
  https://api.odin.fun/v1/v1
  ```

  ```bash Development theme={null}
  https://api.odin.fun/v1/dev
  ```
</CodeGroup>

## Support & Resources

<CardGroup cols={3}>
  <Card title="API Reference" icon="book" href="/api-reference/tokens/get-tokens">
    Complete endpoint documentation with examples
  </Card>

  <Card title="Getting Started Guide" icon="rocket" href="/quickstart/quickstart-01-prepare">
    Step-by-step integration tutorial
  </Card>

  <Card title="Community" icon="discord" href="https://discord.gg/odin">
    Join our Discord for support and updates
  </Card>
</CardGroup>

<Note>
  This API documentation covers all public endpoints. Some administrative functions may require special permissions.
</Note>