Specification

Base URL

https://api.vi.social/v1

Authentication

All API requests must include an API key in the header:

Authorization: Bearer YOUR_API_KEY

Endpoints

Social Wallets

Get Wallet by Social ID

GET /wallets/{platform}/{userId}

Retrieves the public address for a given social media identity.

Parameters:

• platform (string): Social platform identifier (e.g., "x", "tiktok")

• User ID (string): User ID on the specified platform

• appId (string): App ID of the app to retrieve addresses for. Defaults to 'rolodex'', a global address book for everyone.

Response:

{
  "user_id": "string",
  "username": "string",
  "platform": "string",
  "wallets": {
    "base": {
      "address": "string[]"
    },
    "solana": {
      "address": "string[]"
    }
  }
}

Check Wallet Status

GET /wallets/verify/{address}

Checks if a given address is a valid .vi social bound address. If it is, returns that user's social media information.

Parameters:

• address (string): A Solana or EVM public address

Response:

{
  "address": "string",
  "is_vi_address": "boolean",
  "user_id": "string | null",
  "username": "string | null",
  "platform": "string | null",
  "network": "string",
  "vi_display_string": "string
}

Webhooks

Register Webhook

Error Responses

All error responses follow this format:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Error codes:

• 400: Bad Request

• 401: Unauthorized

• 404: Resource Not Found

• 429: Rate Limit Exceeded

• 500: Internal Server Error