openapi: 3.0.3
info:
  title: Kaito Platform API
  version: 2.0.0
  description: >
    Platform services including webhooks and blockchain gateway operations.


    **Webhooks:** Register endpoints for event notifications. Kaito signs
    requests using HMAC-SHA256 with `Kaito-Timestamp` and `Kaito-Signature`
    headers. Events include payment, payout, quote, checkout, identity, and
    acceptance categories.


    **Chain Gateway:** Low-level blockchain operations for Ethereum, Polygon,
    Solana, and Bitcoin. Includes fee estimation and transaction broadcast for
    partners managing their own key material.
  termsOfService: https://developer.kai2.io/terms
  contact:
    name: Kaito Developer Support
    url: https://developer.kai2.io/support
    email: support@kai2.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.kai2.io
    description: Production
  - url: https://sandbox.api.kai2.io
    description: Sandbox
x-tagGroups:
  - name: Webhooks
    tags:
      - Webhook Endpoints
      - Event Types
  - name: Chain Gateway
    tags:
      - Fee Estimation
      - Transaction Broadcast
tags:
  - name: Webhook Endpoints
    description: Manage webhook subscriptions
  - name: Event Types
    description: List available event types
  - name: Fee Estimation
    description: Estimate network fees
  - name: Transaction Broadcast
    description: Broadcast signed transactions
paths:
  /v1/webhooks/endpoints:
    post:
      summary: Register webhook endpoint
      tags:
        - Webhook Endpoints
      description: >
        Register a new webhook endpoint to receive event notifications.


        **Important:** The webhook secret is only returned once at creation
        time.

        Store it securely for signature verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreateRequest'
      responses:
        '201':
          description: Webhook endpoint created
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    get:
      summary: List webhook endpoints
      tags:
        - Webhook Endpoints
      responses:
        '200':
          description: Webhook endpoints list
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /v1/webhooks/endpoints/{endpointId}:
    get:
      summary: Get webhook endpoint
      tags:
        - Webhook Endpoints
      parameters:
        - name: endpointId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook endpoint details
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '404':
          $ref: '#/components/responses/NotFoundError'
    patch:
      summary: Update webhook endpoint
      tags:
        - Webhook Endpoints
      parameters:
        - name: endpointId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointUpdateRequest'
      responses:
        '200':
          description: Webhook endpoint updated
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      summary: Delete webhook endpoint
      tags:
        - Webhook Endpoints
      parameters:
        - name: endpointId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook endpoint deleted
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/webhooks/event-types:
    get:
      summary: List available event types
      tags:
        - Event Types
      responses:
        '200':
          description: Event types
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEventTypes'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /v1/chain/estimate-fee:
    post:
      summary: Estimate network fee for a transfer
      tags:
        - Fee Estimation
      description: |
        Estimate the network fee for a transfer.
        Returns fee estimates for different speed tiers (slow, standard, fast).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateFeeRequest'
      responses:
        '200':
          description: Fee estimate
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateFeeResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /v1/chain/broadcast:
    post:
      summary: Broadcast signed transaction
      tags:
        - Transaction Broadcast
      description: |
        Broadcast a signed transaction to the network.
        Returns the transaction hash and submission status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BroadcastTxRequest'
      responses:
        '200':
          description: Transaction submitted
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BroadcastTxResponse'
        '400':
          description: Bad Request - Invalid transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /v1/chain/transaction/{network}/{txHash}:
    get:
      summary: Get transaction status
      tags:
        - Transaction Broadcast
      description: Check the status of a previously broadcast transaction.
      parameters:
        - name: network
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Network'
        - name: txHash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction status
          headers:
            X-Trace-Id:
              schema:
                $ref: '#/components/schemas/TraceId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatus'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.kai2.io/oauth2/token
          scopes:
            webhooks:write: Create and manage webhook endpoints
            webhooks:read: Read webhook endpoints
            chain:write: Broadcast transactions
            chain:read: Estimate fees and check transaction status
      description: OAuth2 client credentials. All requests must also be made over mTLS.
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid.
    NotFoundError:
      description: The requested resource does not exist.
  schemas:
    TraceId:
      type: string
      description: Correlation id for troubleshooting
      example: trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B
    ErrorResponse:
      type: object
      required:
        - error
        - traceId
      properties:
        traceId:
          $ref: '#/components/schemas/TraceId'
        error:
          type: object
          properties:
            code:
              type: string
              example: INVALID_REQUEST
            message:
              type: string
              example: Invalid webhook URL
            details:
              type: object
              additionalProperties: true
    WebhookEndpointCreateRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          example: https://partner.example/webhooks/kaito
        secret:
          type: string
          nullable: true
          description: >
            Secret used for signature validation (HMAC-SHA256).

            If omitted, Kaito will generate one and return it once at creation
            time.
        events:
          type: array
          items:
            type: string
          example:
            - payment.succeeded
            - payout.completed
    WebhookEndpointUpdateRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        enabled:
          type: boolean
    WebhookEndpoint:
      type: object
      required:
        - endpointId
        - url
        - events
        - createdAt
      properties:
        endpointId:
          type: string
          example: whk_01JH...
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        enabled:
          type: boolean
          default: true
        createdAt:
          type: string
          format: date-time
    WebhookEndpointCreateResponse:
      type: object
      required:
        - endpoint
        - secret
      properties:
        endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
        secret:
          type: string
          description: Returned only once. Store securely.
          example: whsec_XXXX
    WebhookEvent:
      type: object
      required:
        - id
        - type
        - createdAt
        - data
      properties:
        id:
          type: string
          example: evt_01JH...
        type:
          type: string
          example: payment.succeeded
        createdAt:
          type: string
          format: date-time
        data:
          type: object
          additionalProperties: true
          description: Event payload (varies by type).
        traceId:
          $ref: '#/components/schemas/TraceId'
    WebhookEventTypes:
      type: object
      description: Available webhook event types organized by category
      properties:
        payment:
          type: array
          items:
            type: string
          example:
            - payment.created
            - payment.succeeded
            - payment.failed
        payout:
          type: array
          items:
            type: string
          example:
            - payout.created
            - payout.completed
            - payout.failed
        quote:
          type: array
          items:
            type: string
          example:
            - quote.expired
        checkout:
          type: array
          items:
            type: string
          example:
            - checkout.session.created
            - checkout.session.completed
            - checkout.session.expired
        identity:
          type: array
          items:
            type: string
          example:
            - kyc.approved
            - kyc.rejected
            - kyb.approved
            - kyb.rejected
        acceptance:
          type: array
          items:
            type: string
          example:
            - charge.succeeded
            - charge.failed
            - refund.succeeded
    Network:
      type: string
      enum:
        - ethereum
        - polygon
        - solana
        - bitcoin
    FeeTier:
      type: string
      enum:
        - slow
        - standard
        - fast
      example: standard
    EstimateFeeRequest:
      type: object
      required:
        - network
        - from
        - to
        - asset
        - amount
      properties:
        network:
          $ref: '#/components/schemas/Network'
        from:
          type: string
          description: Sender address
        to:
          type: string
          description: Recipient address
        asset:
          type: string
          description: Asset symbol (e.g., USDT, ETH)
          example: USDT
        amount:
          type: string
          description: Amount to transfer
          example: '10.0'
    FeeEstimate:
      type: object
      properties:
        amount:
          type: string
          example: '0.12'
        currency:
          type: string
          description: Native currency of the network
          example: MATIC
        tier:
          $ref: '#/components/schemas/FeeTier'
    EstimateFeeResponse:
      type: object
      required:
        - network
        - estimatedFee
      properties:
        network:
          $ref: '#/components/schemas/Network'
        estimatedFee:
          $ref: '#/components/schemas/FeeEstimate'
        alternatives:
          type: array
          description: Fee estimates for other tiers
          items:
            $ref: '#/components/schemas/FeeEstimate'
    BroadcastTxRequest:
      type: object
      required:
        - network
        - signedTx
      properties:
        network:
          $ref: '#/components/schemas/Network'
        signedTx:
          type: string
          description: Raw signed transaction (hex encoded).
    BroadcastStatus:
      type: string
      enum:
        - submitted
    BroadcastTxResponse:
      type: object
      required:
        - hash
        - status
      properties:
        hash:
          type: string
          description: Transaction hash
          example: 0xabc...
        status:
          $ref: '#/components/schemas/BroadcastStatus'
    TransactionConfirmationStatus:
      type: string
      enum:
        - pending
        - confirmed
        - failed
    TransactionStatus:
      type: object
      required:
        - hash
        - network
        - status
      properties:
        hash:
          type: string
        network:
          $ref: '#/components/schemas/Network'
        status:
          $ref: '#/components/schemas/TransactionConfirmationStatus'
        confirmations:
          type: integer
          description: Number of block confirmations
        blockNumber:
          type: integer
          nullable: true
        timestamp:
          type: string
          format: date-time
          nullable: true
security:
  - oAuth2: []
