API Reference

API reference for SonicClout platform

SonicClout provides a set of APIs for interacting with the platform programmatically. This reference documents the available endpoints, authentication requirements, and example requests.

Base URLs

  • Production API: https://api.sonicclout.io/v1

  • Staging API: https://api-staging.sonicclout.io/v1

  • Local Development: http://localhost:3001/v1

Authentication

Most API endpoints require authentication using a JWT token:

Authorization: Bearer <token>

To obtain a token, use the /auth/login endpoint with your credentials.

Rate Limiting

API requests are rate limited to:

  • 100 requests per minute for authenticated users

  • 20 requests per minute for unauthenticated users

Exceeding these limits will result in a 429 Too Many Requests response.

Content Endpoints

List Content

GET /content

Returns a paginated list of content tokens.

Query Parameters

Parameter
Type
Description

page

number

Page number (default: 1)

limit

number

Items per page (default: 20, max: 100)

sort

string

Sort field (created_at, popularity, price)

order

string

Sort order (asc, desc)

creator

string

Filter by creator address

type

string

Filter by content type (post, image, video, etc.)

Response Example

{
  "data": [
    {
      "id": "content_12345",
      "name": "My Awesome Content",
      "symbol": "MAC",
      "content_type": "post",
      "content_hash": "QmHash...",
      "creator_address": "7Zb1...FbK2",
      "total_supply": 1000000,
      "current_price": 0.5,
      "created_at": "2023-06-15T12:00:00Z",
      "metadata": {
        "title": "My First Content",
        "description": "This is my first tokenized content!",
        "image_url": "https://sonicclout.io/content/12345.png"
      }
    },
    // More content items...
  ],
  "pagination": {
    "total_items": 156,
    "total_pages": 8,
    "current_page": 1,
    "limit": 20
  }
}

Get Content Details

GET /content/:id

Returns detailed information about a specific content token.

Path Parameters

Parameter
Type
Description

id

string

Content ID

Response Example

{
  "id": "content_12345",
  "name": "My Awesome Content",
  "symbol": "MAC",
  "content_type": "post",
  "content_hash": "QmHash...",
  "creator_address": "7Zb1...FbK2",
  "total_supply": 1000000,
  "current_price": 0.5,
  "created_at": "2023-06-15T12:00:00Z",
  "metadata": {
    "title": "My First Content",
    "description": "This is my first tokenized content!",
    "image_url": "https://sonicclout.io/content/12345.png"
  },
  "social_metrics": {
    "views": 15240,
    "likes": 1250,
    "shares": 342,
    "comments": 89
  },
  "token_metrics": {
    "holders": 156,
    "volume_24h": 25000,
    "price_change_24h": 5.2
  }
}

Create Content

POST /content

Creates a new content token.

Request Body

{
  "name": "My New Content",
  "symbol": "MNC",
  "content_type": "image",
  "total_supply": 500000,
  "decimals": 9,
  "metadata": {
    "title": "My New Artwork",
    "description": "A beautiful digital artwork",
    "image_url": "https://example.com/my-artwork.png"
  }
}

Response Example

{
  "id": "content_67890",
  "name": "My New Content",
  "symbol": "MNC",
  "content_type": "image",
  "content_hash": "QmNewHash...",
  "creator_address": "7Zb1...FbK2",
  "total_supply": 500000,
  "current_price": 0,
  "created_at": "2023-08-22T15:30:00Z",
  "transaction_id": "4xT2...jK9z",
  "metadata": {
    "title": "My New Artwork",
    "description": "A beautiful digital artwork",
    "image_url": "https://example.com/my-artwork.png"
  }
}

Vesting Endpoints

List Vesting Schedules

GET /vesting

Returns a list of vesting schedules for the authenticated user.

Response Example

{
  "data": [
    {
      "id": "vesting_12345",
      "token_id": "content_12345",
      "token_name": "My Awesome Content",
      "token_symbol": "MAC",
      "total_amount": 1000000,
      "unlocked_amount": 200000,
      "metric_type": "followers",
      "milestones": [
        {
          "threshold": 1000,
          "percentage": 20,
          "status": "reached"
        },
        {
          "threshold": 5000,
          "percentage": 30,
          "status": "pending"
        },
        {
          "threshold": 10000,
          "percentage": 50,
          "status": "pending"
        }
      ],
      "created_at": "2023-06-15T12:00:00Z"
    },
    // More vesting schedules...
  ]
}

Create Vesting Schedule

POST /vesting

Creates a new vesting schedule.

Request Body

{
  "token_id": "content_12345",
  "amount": 1000000,
  "metric_type": "followers",
  "milestones": [
    {
      "threshold": 1000,
      "percentage": 20
    },
    {
      "threshold": 5000,
      "percentage": 30
    },
    {
      "threshold": 10000,
      "percentage": 50
    }
  ]
}

Response Example

{
  "id": "vesting_67890",
  "token_id": "content_12345",
  "token_name": "My Awesome Content",
  "token_symbol": "MAC",
  "total_amount": 1000000,
  "unlocked_amount": 0,
  "metric_type": "followers",
  "milestones": [
    {
      "threshold": 1000,
      "percentage": 20,
      "status": "pending"
    },
    {
      "threshold": 5000,
      "percentage": 30,
      "status": "pending"
    },
    {
      "threshold": 10000,
      "percentage": 50,
      "status": "pending"
    }
  ],
  "created_at": "2023-08-22T15:30:00Z",
  "transaction_id": "5yU3...kL0a"
}

Check Milestones

POST /vesting/:id/check

Checks milestone status for a vesting schedule.

Path Parameters

Parameter
Type
Description

id

string

Vesting schedule ID

Response Example

{
  "id": "vesting_12345",
  "current_metric_value": 1200,
  "milestones": [
    {
      "threshold": 1000,
      "percentage": 20,
      "status": "reached"
    },
    {
      "threshold": 5000,
      "percentage": 30,
      "status": "pending"
    },
    {
      "threshold": 10000,
      "percentage": 50,
      "status": "pending"
    }
  ],
  "unlocked_amount": 200000,
  "unlocked_percentage": 20,
  "transaction_id": "6zV4...lM1b"
}

Trading Endpoints

Get Token Pairs

GET /trading/pairs

Returns available token pairs for trading.

Response Example

{
  "data": [
    {
      "id": "pair_12345",
      "token0": {
        "id": "content_12345",
        "name": "My Awesome Content",
        "symbol": "MAC",
        "decimals": 9
      },
      "token1": {
        "id": "SOL",
        "name": "Solana",
        "symbol": "SOL",
        "decimals": 9
      },
      "price": 0.5,
      "volume_24h": 125000,
      "liquidity": 250000,
      "fee_tier": 0.3
    },
    // More pairs...
  ]
}

Get Swap Quote

GET /trading/quote

Returns a quote for a token swap.

Query Parameters

Parameter
Type
Description

tokenIn

string

Input token ID or address

tokenOut

string

Output token ID or address

amountIn

string

Input amount (in smallest units)

slippage

number

Maximum slippage percentage

Response Example

{
  "id": "quote_12345",
  "tokenIn": "content_12345",
  "tokenInSymbol": "MAC",
  "amountIn": "1000000000",
  "tokenOut": "SOL",
  "tokenOutSymbol": "SOL",
  "amountOut": "500000000",
  "minAmountOut": "495000000",
  "price": 0.5,
  "priceImpact": 0.2,
  "fee": "3000000",
  "route": [
    {
      "poolId": "pool_12345",
      "tokenIn": "content_12345",
      "tokenOut": "SOL",
      "fee": 0.3
    }
  ],
  "expires_at": "2023-08-22T15:35:00Z"
}

User Endpoints

Get User Profile

GET /users/me

Returns the profile of the authenticated user.

Response Example

{
  "id": "user_12345",
  "address": "7Zb1...FbK2",
  "username": "creator123",
  "display_name": "Amazing Creator",
  "bio": "Creating awesome content on SonicClout",
  "profile_image": "https://sonicclout.io/profiles/creator123.png",
  "social_metrics": {
    "followers": 1250,
    "following": 350,
    "content_count": 15
  },
  "creator_metrics": {
    "total_content": 5,
    "total_volume": 250000,
    "total_holders": 325
  },
  "created_at": "2023-01-15T12:00:00Z"
}

Get Creator Profile

GET /users/:address

Returns the profile of a specific creator.

Path Parameters

Parameter
Type
Description

address

string

Creator's wallet address

Response Example

{
  "id": "user_67890",
  "address": "8Ac2...GcL3",
  "username": "famous_creator",
  "display_name": "Famous Creator",
  "bio": "Top creator on SonicClout",
  "profile_image": "https://sonicclout.io/profiles/famous_creator.png",
  "social_metrics": {
    "followers": 25000,
    "following": 150,
    "content_count": 45
  },
  "creator_metrics": {
    "total_content": 30,
    "total_volume": 1500000,
    "total_holders": 2500
  },
  "created_at": "2022-10-05T09:30:00Z"
}

Error Responses

All API endpoints return standard error responses:

400 Bad Request

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid parameters",
    "details": {
      "name": "Name is required"
    }
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred"
  }
}

Webhooks

SonicClout provides webhooks for real-time event notifications. To set up a webhook:

  1. Register a webhook URL in your account settings

  2. Select the events you want to receive

  3. Implement an endpoint to receive the webhook events

Event Types

  • content.created - New content token created

  • vesting.milestone_reached - Vesting milestone reached

  • trade.completed - Trade transaction completed

  • bond.issued - New bond issued

  • bond.redeemed - Bond redeemed

Example Webhook Payload

{
  "id": "evt_12345",
  "type": "content.created",
  "created_at": "2023-08-22T15:30:00Z",
  "data": {
    "content_id": "content_67890",
    "name": "My New Content",
    "symbol": "MNC",
    "creator_address": "7Zb1...FbK2",
    "transaction_id": "4xT2...jK9z"
  }
}
PreviousFrontend Architecture

Last updated