openapi: 3.1.0
info:
  title: Talise Bridge API
  version: 1.0.0
  description: One-way routes from supported origin chains into Sui. Source payments are signed by the user's wallet.
servers:
  - url: https://bridge.talise.io/api/v1/bridge
security:
  - PartnerKey: []
components:
  securitySchemes:
    PartnerKey:
      type: http
      scheme: bearer
      description: A Talise-issued tb_live_ API key. Keep it on your server.
  schemas:
    RouteInput:
      type: object
      additionalProperties: false
      required: [chainId, token, amount, sender, recipient, receive]
      properties:
        chainId: { type: integer, minimum: 1 }
        token: { type: string, description: Token address from the catalogue }
        amount: { type: string, pattern: '^[1-9][0-9]{0,29}$', description: Source token base units }
        sender: { type: string, description: Source wallet address }
        recipient: { type: string, description: Destination Sui address }
        receive: { type: string, enum: [USDsui, SUI] }
    Error:
      type: object
      required: [error]
      properties:
        error: { type: string }
        code: { type: string }
    Route:
      type: object
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [awaiting_source_transaction, converting, delivered, needs_attention] }
        provider: { type: string, enum: [socket, near] }
        expiresAt: { type: string, format: date-time }
        from: { type: object }
        to: { type: object }
        estimate: { type: object }
        fees: { type: object }
        source: { type: object, description: Source transaction or deposit instructions; for Solana includes the separate fee payment }
paths:
  /chains:
    get:
      security: []
      summary: Discover supported source networks
      responses:
        '200': { description: Chain catalogue and freshness indicators }
  /tokens:
    get:
      security: []
      summary: List tokens for a source network
      parameters:
        - in: query
          name: chainId
          required: true
          schema: { type: integer, minimum: 1 }
      responses:
        '200': { description: Tokens and their base-unit decimals }
  /quotes:
    post:
      summary: Preview a route without reserving a deposit address
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RouteInput' }
      responses:
        '200':
          description: Advisory estimate only; no source payment instructions or reserved deposit address
          content:
            application/json:
              schema:
                type: object
                properties:
                  quote: { $ref: '#/components/schemas/Route' }
        '401': { description: Missing or invalid API key }
        '429': { description: Rate limit exceeded; inspect Retry-After }
  /routes:
    post:
      summary: Create a live route
      description: Retry the same request with the same Idempotency-Key after a timeout. A different body with the same key returns 409.
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema: { type: string, minLength: 16, maxLength: 128 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RouteInput' }
      responses:
        '201':
          description: Live route created
          content:
            application/json:
              schema:
                type: object
                properties:
                  route: { $ref: '#/components/schemas/Route' }
        '200': { description: Exact replay of a previously created route }
        '409': { description: Key in use or reused for different parameters }
        '429': { description: Rate limit exceeded; inspect Retry-After }
  /routes/{id}:
    get:
      summary: Read source and Sui delivery status
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Route and delivery status
          content:
            application/json:
              schema:
                type: object
                properties:
                  route: { $ref: '#/components/schemas/Route' }
                  status: { type: string, enum: [awaiting_source_transaction, converting, delivered, needs_attention] }
                  sourceStatus: { type: string }
                  sourceDestinationTx: { type: [string, 'null'] }
                  deliveryTx: { type: [string, 'null'] }
        '404': { description: Unknown route or one belonging to another partner }
  /routes/{id}/complete:
    post:
      summary: Advance a Sui conversion after source delivery
      description: Safe to retry. Talise reuses the same prepared transaction after an uncertain broadcast.
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Delivered, pending, or needs attention }
        '404': { description: Unknown route or one belonging to another partner }