proxmox/docs/api/openapi-multi-chain-execution.yaml

openapi: 3.1.0
info:
  title: Multi-Chain Execution and Mirroring API
  version: 0.1.0

servers:
  - url: http://localhost:3001

paths:
  /v1/routes/chain138-to-usdtz:
    post:
      summary: Get route plans for Chain138 to Tezos USDtz
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                source_chain_id: { type: integer, default: 138 }
                source_asset: { type: string }
                source_amount: { type: string }
                destination_tezos_address: { type: string }
                max_slippage_bps: { type: integer }
                max_total_fees: { type: string }
                prefer_non_custodial: { type: boolean }
      responses:
        '200':
          description: Route plans
        '400':
          description: Validation error

  /v1/routes/non-evm-families:
    get:
      summary: List non-EVM route families (Tezos, Solana, Tron, XRPL) and supported source chains
      responses:
        '200':
          description: family metadata and supported_source_chain_ids (138, 651940)

  /v1/routes/plan-non-evm:
    post:
      summary: Multi-hop route plan from Chain 138 or ALL Mainnet through Ethereum hub to a non-EVM destination
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [destination_family, destination_address]
              properties:
                destination_family:
                  type: string
                  enum: [tezos_usdtz, solana_usdc, tron_usdt, xrpl_usdc]
                destination_address:
                  type: string
                  description: Destination address validated per family (Tezos tz1… / Solana base58 / Tron T… / XRPL r…)
                source_chain_id: { type: integer, default: 138 }
                source_asset: { type: string, description: Defaults to cUSDC on 138 or AUSDC on 651940 when omitted }
                source_amount: { type: string }
                async_quotes:
                  type: boolean
                  description: Reserved for future enrichment (Tezos path uses chain138-to-usdtz with async_quotes)
      responses:
        '200':
          description: Route plan with hops, optional quote_hints (aggregator / bridge entry points), destination_family
        '400':
          description: Validation error

  /v1/intents:
    post:
      summary: Create intent
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [type, chain_from, chain_to, asset_in, asset_out, amount]
              properties:
                type: { type: string }
                chain_from: { type: integer }
                chain_to: { type: integer }
                asset_in: { type: string }
                asset_out: { type: string }
                amount: { type: string }
                idempotency_key: { type: string }
      responses:
        '201':
          description: Intent created
        '400':
          description: Validation error

  /v1/intents/{intentId}/execute:
    post:
      summary: Execute intent
      parameters:
        - name: intentId
          in: path
          required: true
          schema: { type: string }
      responses:
        '202':
          description: Execution started
        '400':
          description: Bad request

  /v1/executions/{executionId}:
    get:
      summary: Get execution status
      parameters:
        - name: executionId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Execution
        '404':
          description: Not found

  /v1/tx/{chainId}/{txHash}:
    get:
      summary: Get normalized receipt and logs
      parameters:
        - name: chainId
          in: path
          required: true
          schema: { type: integer }
        - name: txHash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Receipt and logs
        '404':
          description: Not found

  /v1/mirror/commit:
    post:
      summary: Trigger Merkle commit
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [chain_id, leaves]
              properties:
                chain_id: { type: integer }
                leaves: { type: array }
                uri: { type: string }
      responses:
        '201':
          description: Commit created
        '400':
          description: Bad request

  /v1/mirror/commits/{commitId}:
    get:
      summary: Get commit metadata
      parameters:
        - name: commitId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Commit
        '404':
          description: Not found

  /v1/mirror/proof:
    get:
      summary: Get Merkle proof for tx
      parameters:
        - name: chain_id
          in: query
          required: true
          schema: { type: integer }
        - name: tx_hash
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Leaf, proof, root
        '404':
          description: No proof found

  /v1/health:
    get:
      summary: Health and circuit breaker status
      responses:
        '200':
          description: ok or degraded

  /v1/metrics:
    get:
      summary: Prometheus metrics
      responses:
        '200':
          description: text/plain

  /v1/admin/policies:
    post:
      summary: Update policies (stub, protected)
      responses:
        '200':
          description: Accepted
        '401':
          description: Unauthorized

  /v1/admin/keys/rotate:
    post:
      summary: Rotate keys (stub, protected)
      responses:
        '200':
          description: Accepted
        '401':
          description: Unauthorized

  /v1/admin/circuit-breaker/on:
    post:
      summary: Force circuit breaker open (protected)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized

  /v1/admin/circuit-breaker/off:
    post:
      summary: Force circuit breaker closed (protected)
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized