openapi: 3.2.0
info:
  title: tZERO Institutional API Documents Tokens API
  description: '## Overview


    The **tZERO Institutional API** — programmatic access to transfer-agent, tokenization, and custody operations for institutional issuers and partners.'
  version: 1.1.0
  contact:
    name: T0kenizer API Support
    email: api@t0direct.com
servers:
- url: https://api.t0direct.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Tokens
  description: Token configurations — the issuer's token blueprints
paths:
  /api/v1/tokens/:
    get:
      summary: List tokens
      tags:
      - Tokens
      description: Returns a paginated list of token configurations for the authenticated issuer, each with its on-chain deployments.
      parameters:
      - schema:
          type: integer
          default: 1
          minimum: 1
        in: query
        name: page
        required: false
        description: Page number
      - schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
        in: query
        name: perPage
        required: false
        description: Results per page
      - schema:
          type: boolean
          default: false
        in: query
        name: includeDelisted
        required: false
        description: Include delisted tokens
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/def-2'
                  pagination:
                    $ref: '#/components/schemas/def-0'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/def-1'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/def-1'
      operationId: getApiV1Tokens
      x-operation-id-source: derived
  /api/v1/tokens/{id}:
    get:
      summary: Get token
      tags:
      - Tokens
      description: Returns a single token configuration (with deployments) owned by the authenticated issuer.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Token configuration ID
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/def-2'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/def-1'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/def-1'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/def-1'
      operationId: getApiV1TokensById
      x-operation-id-source: derived
components:
  schemas:
    def-2:
      type: object
      description: A token configuration (the blueprint). Deployments are its on-chain instances.
      properties:
        id:
          type: string
          description: CUID
        name:
          type: string
        symbol:
          type: string
        decimals:
          type: integer
          example: 18
        initialSupply:
          type: string
          description: Integer as string
        supplyCap:
          type:
          - string
          - 'null'
          description: Integer as string
        price:
          type:
          - number
          - 'null'
        assetType:
          type:
          - string
          - 'null'
        assetClass:
          type:
          - string
          - 'null'
          description: e.g. "t-bill", "mmf", "private-credit"
        tokenStandard:
          type:
          - string
          - 'null'
        mintable:
          type: boolean
        burnable:
          type: boolean
        pausable:
          type: boolean
        upgradeable:
          type: boolean
        whitelistEnabled:
          type: boolean
        blacklistEnabled:
          type: boolean
        snapshotEnabled:
          type: boolean
        imported:
          type: boolean
        delisted:
          type: boolean
        lifecycleStatus:
          type: string
          example: DRAFT
        createdAt:
          type: string
          format: date-time
        deployments:
          type: array
          items:
            $ref: '#/components/schemas/def-3'
      title: TokenConfig
    def-0:
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching records
        page:
          type: integer
          description: Current page number
        perPage:
          type: integer
          description: Records per page
        totalPages:
          type: integer
          description: Total number of pages
      title: PaginationMeta
    def-3:
      type: object
      description: An on-chain instance of a token configuration on a specific chain/network.
      properties:
        id:
          type: string
        tokenConfigId:
          type: string
        chain:
          type: string
          description: Target chain (e.g. ETHEREUM, POLYGON, BESU)
        network:
          type: string
          description: MAINNET / TESTNET / DEVNET
        contractAddress:
          type:
          - string
          - 'null'
        txHash:
          type:
          - string
          - 'null'
        status:
          type: string
          example: DEPLOYED
        walletAddress:
          type:
          - string
          - 'null'
        deployedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
      title: Deployment
    def-1:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: T0K-V1-INV-001
            message:
              type: string
              example: Investor not found
      title: ErrorResponse
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key generated at app.t0kenizer.com/ta/api-keys