openapi: 3.0.3
info:
  title: "Toknex API"
  version: "1.0.0"
  description: |
    Accept USDT (BEP-20) on BNB Smart Chain. Each customer gets a permanent deposit address; deposits are confirmed
    after 12 blocks and reported by signed webhooks. Amounts are decimal strings, never floats.
servers:
  - url: "https://api.toknex.space"
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Secret key from the dashboard (sk_live_...). Server-side only."
  parameters:
    UserId:
      name: id
      in: path
      required: true
      description: Our numeric user id or your external_id.
      schema: { type: string }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, pattern: '^[A-Za-z0-9_\-:.]{8,100}$' }
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
    StartingAfter:
      name: starting_after
      in: query
      description: Return items with a smaller id (older).
      schema: { type: integer }
    SinceId:
      name: since_id
      in: query
      description: Return items with a larger id (newer).
      schema: { type: integer }
    Status:
      name: status
      in: query
      schema: { $ref: '#/components/schemas/DepositStatus' }
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: { type: string, example: validation_failed }
            message: { type: string }
            fields: { type: object, additionalProperties: { type: string } }
            retry_after: { type: integer }
    Amount:
      type: string
      pattern: '^\d+\.\d{18}$'
      example: "500.000000000000000000"
    AmountRaw:
      type: string
      pattern: '^\d+$'
      description: Exact integer in token base units (18 decimals).
      example: "500000000000000000000"
    DepositStatus:
      type: string
      enum: [DETECTED, CONFIRMING, CONFIRMED, COLLECTION_PENDING, COLLECTION_SUBMITTED, COLLECTED, FAILED, REORGED]
    UserCreate:
      type: object
      required: [name]
      properties:
        name: { type: string, maxLength: 150 }
        external_id: { type: string, maxLength: 100, pattern: '^[A-Za-z0-9_.:\-]+$' }
        email: { type: string, format: email }
        metadata: { type: object, additionalProperties: true }
        create_wallet: { type: boolean, default: true }
    User:
      type: object
      properties:
        id: { type: integer }
        external_id: { type: string, nullable: true }
        name: { type: string }
        email: { type: string, nullable: true }
        status: { type: string, enum: [ACTIVE, SUSPENDED] }
        created_at: { type: string, format: date-time }
        deposit_wallet: { $ref: '#/components/schemas/DepositWallet' }
    DepositWallet:
      type: object
      properties:
        user_id: { type: integer }
        external_id: { type: string, nullable: true }
        network: { type: string, example: BSC }
        network_name: { type: string, example: BNB Smart Chain }
        chain_id: { type: integer, example: 56 }
        token: { type: string, example: USDT }
        token_standard: { type: string, example: BEP-20 }
        token_contract: { type: string }
        deposit_address: { type: string, example: "0x3fA1c6d1B0F5f1E2d6C4b9A8e7D3c2B1a0F9e8D7" }
        deployed: { type: boolean }
        status: { type: string, enum: [ACTIVE, PAUSED, DISABLED] }
        minimum_deposit: { type: string }
        required_confirmations: { type: integer }
        qr_payload: { type: string }
    Deposit:
      type: object
      properties:
        id: { type: integer }
        user_id: { type: integer }
        external_id: { type: string, nullable: true }
        network: { type: string }
        token: { type: string }
        deposit_address: { type: string }
        from_address: { type: string }
        tx_hash: { type: string }
        log_index: { type: integer }
        block_number: { type: integer }
        amount: { $ref: '#/components/schemas/Amount' }
        amount_raw: { $ref: '#/components/schemas/AmountRaw' }
        confirmations: { type: integer }
        required_confirmations: { type: integer }
        status: { $ref: '#/components/schemas/DepositStatus' }
        credited: { type: boolean }
        below_minimum: { type: boolean }
        explorer_url: { type: string }
        detected_at: { type: string, format: date-time, nullable: true }
        confirmed_at: { type: string, format: date-time, nullable: true }
        collected_at: { type: string, format: date-time, nullable: true }
    DepositList:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Deposit' } }
        has_more: { type: boolean }
    UserBalance:
      type: object
      properties:
        user_id: { type: integer }
        token: { type: string }
        confirmed_balance: { $ref: '#/components/schemas/Amount' }
        confirmed_balance_raw: { $ref: '#/components/schemas/AmountRaw' }
        pending_confirmation: { $ref: '#/components/schemas/Amount' }
        pending_confirmation_raw: { $ref: '#/components/schemas/AmountRaw' }
        awaiting_collection: { $ref: '#/components/schemas/Amount' }
        awaiting_collection_raw: { $ref: '#/components/schemas/AmountRaw' }
    WebhookEvent:
      type: object
      properties:
        id: { type: string, example: evt_7731 }
        type: { type: string, enum: [deposit.detected, deposit.confirmed, deposit.collected, settlement.approved, settlement.paid, ping] }
        created: { type: integer }
        data: { oneOf: [ { $ref: '#/components/schemas/Deposit' }, { type: object } ] }
paths:
  /api/v1/status:
    get:
      summary: Network and service status
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  network: { type: string }
                  network_name: { type: string }
                  chain_id: { type: integer }
                  token: { type: string }
                  token_standard: { type: string }
                  token_contract: { type: string }
                  required_confirmations: { type: integer }
                  minimum_deposit: { type: string }
                  collection_paused: { type: boolean, nullable: true }
  /api/v1/users:
    post:
      summary: Create a customer (and deposit address)
      parameters: [ { $ref: '#/components/parameters/IdempotencyKey' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UserCreate' }
      responses:
        "201": { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/User' } } } }
        "200": { description: Existing user with this external_id, content: { application/json: { schema: { $ref: '#/components/schemas/User' } } } }
        "422": { $ref: '#/components/responses/Error' }
  /api/v1/users/{id}:
    get:
      summary: Get a customer
      parameters: [ { $ref: '#/components/parameters/UserId' } ]
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/User' } } } }
        "404": { $ref: '#/components/responses/Error' }
  /api/v1/users/{id}/deposit-wallet:
    get:
      summary: Get the customer's deposit address
      parameters: [ { $ref: '#/components/parameters/UserId' } ]
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/DepositWallet' } } } }
        "404": { $ref: '#/components/responses/Error' }
    post:
      summary: Create (or return) the customer's deposit address
      parameters: [ { $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' } ]
      responses:
        "201": { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/DepositWallet' } } } }
        "200": { description: Already existed, content: { application/json: { schema: { $ref: '#/components/schemas/DepositWallet' } } } }
  /api/v1/users/{id}/deposits:
    get:
      summary: Customer deposits
      parameters: [ { $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/Status' }, { $ref: '#/components/parameters/Limit' }, { $ref: '#/components/parameters/StartingAfter' }, { $ref: '#/components/parameters/SinceId' } ]
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/DepositList' } } } }
  /api/v1/users/{id}/collections:
    get:
      summary: Sweeps of this customer's address to the treasury
      parameters: [ { $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/Limit' } ]
      responses:
        "200": { description: OK }
  /api/v1/users/{id}/balance:
    get:
      summary: Customer confirmed and pending totals
      parameters: [ { $ref: '#/components/parameters/UserId' } ]
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/UserBalance' } } } }
  /api/v1/users/{id}/portal-link:
    post:
      summary: One-time hosted deposit page link (30 minutes)
      parameters: [ { $ref: '#/components/parameters/UserId' } ]
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string }
                  expires_at: { type: string, format: date-time }
  /api/v1/deposits:
    get:
      summary: All deposits of your customers
      parameters: [ { $ref: '#/components/parameters/Status' }, { $ref: '#/components/parameters/Limit' }, { $ref: '#/components/parameters/StartingAfter' }, { $ref: '#/components/parameters/SinceId' } ]
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/DepositList' } } } }
  /api/v1/deposits/{depositId}:
    get:
      summary: One deposit
      parameters:
        - { name: depositId, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Deposit' } } } }
        "404": { $ref: '#/components/responses/Error' }
  /api/v1/balance:
    get:
      summary: Your merchant balance
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  balance: { $ref: '#/components/schemas/Amount' }
                  balance_raw: { $ref: '#/components/schemas/AmountRaw' }
                  available_for_settlement: { $ref: '#/components/schemas/Amount' }