openapi: 3.1.0
info:
  title: Clusters Authentication Registration API
  version: '1.0'
  description: Clusters is a multichain namespace and identity service that gives users a single universal name (username/wallet) resolvable across EVM, Solana, and other blockchain ecosystems. The v1 REST API resolves addresses to cluster names and back, reads cluster profiles, checks name availability, produces registration transaction data, manages community clusters, and streams a replayable historical event feed. Read endpoints are public; write/manage endpoints require a wallet-signature bearer token. An optional API key raises rate limits.
  contact:
    name: Clusters
    url: https://docs.clusters.xyz
  x-apievangelist-provenance:
    method: generated
    source: https://docs.clusters.xyz/getting-started/api/v1
    note: Faithfully modeled from the provider's published v1 documentation; the Clusters team does not publish an OpenAPI definition. Base URL verified live 2026-07-18.
servers:
- url: https://api.clusters.xyz/v1
  description: Production v1
security:
- ApiKeyAuth: []
- {}
tags:
- name: Registration
  description: Check availability and build registration transaction data
paths:
  /names/register/check:
    post:
      operationId: checkNameAvailability
      tags:
      - Registration
      summary: Check availability
      description: Check the availability of one or more cluster names.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Availability results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Availability'
  /names/register/evm:
    post:
      operationId: getRegistrationDataEvm
      tags:
      - Registration
      summary: Get EVM registration data
      description: Get the transaction data for registering a cluster name on an EVM chain so a user can sign it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
      responses:
        '200':
          description: Registration transaction data
          content:
            application/json:
              schema:
                type: object
  /names/register/solana:
    post:
      operationId: getRegistrationDataSolana
      tags:
      - Registration
      summary: Get Solana registration data
      description: Get the transaction data for registering a cluster name on Solana so a user can sign it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationRequest'
      responses:
        '200':
          description: Registration transaction data
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Availability:
      type: object
      properties:
        name:
          type: string
        isAvailable:
          type: boolean
    RegistrationRequest:
      type: object
      required:
      - network
      - sender
      - names
      properties:
        network:
          type: string
          description: Chain id (e.g. "1", "10", "8453") or "solana".
        sender:
          type: string
        names:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              amountWei:
                type: string
        referralClusterId:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Optional API key from https://clusters.xyz/developer to raise rate limits.
    WalletBearerAuth:
      type: http
      scheme: bearer
      description: Wallet-signature auth token obtained from POST /auth/token.