M0 Topology API

openapi: 3.0.1
info:
  title: liquidity-api Order Topology API
  version: ''
  description: This API provides quotes for moving and converting between M extensions and other stablecoins
servers:
- url: https://gateway.m0.xyz/v1/orchestration
  description: mainnet
- url: https://gateway.stage.m0.xyz/v1/orchestration
  description: stage
- url: https://gateway.dev.m0.xyz/v1/orchestration
  description: devnet
- url: http://localhost:5600
  description: localnet
tags:
- name: Topology
paths:
  /topology/routes:
    get:
      description: 'Returns all known routes in the system. Routes are seeded from the

        static asset graph on startup and enriched by live quote traffic.

        This is a read-only view of routing knowledge — not the routing

        logic itself. Use lastUsed and totalQuoteCount to gauge confidence.


        **Error responses**


        Errors return `commons.ErrorBody` (`{ code, message, requestId }`);

        branch on `code`, not the HTTP status.


        | Status | `code`               | When                                                                       |

        | ------ | -------------------- | -------------------------------------------------------------------------- |

        | 400    | `BadTopologyRequest` | Invalid query params: only one of `sourceChain` / `sourceAddress`, or an unknown asset. |'
      operationId: topology_getRoutes
      tags:
      - Topology
      parameters:
      - name: sourceChain
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Chain'
          nullable: true
      - name: sourceAddress
        in: query
        required: false
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopologyRoute'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - ApiKeyAuth: []
  /topology/stats:
    get:
      description: Aggregated statistics about route usage
      operationId: topology_getRouteStats
      tags:
      - Topology
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopologyRouteStats'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    Chain:
      title: Chain
      type: string
      enum:
      - Ethereum
      - Solana
      - Arbitrum
      - Base
      - Linea
      - Sepolia
      - BaseSepolia
      - ArbitrumSepolia
      - HyperEVM
      - BinanceSmartChain
      - Mantra
      - Plasma
      - SolanaDevnet
      - Soneium
      - Citrea
      - Fluent
      - Moca
      - Rise
    ErrorBody:
      title: ErrorBody
      type: object
      description: 'Standard error response body. Every error response from this API

        returns this shape.'
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: Stable machine-readable identifier for the failure mode.
        message:
          type: string
          description: Human-readable description of what went wrong. Safe to surface in UI.
        requestId:
          type: string
          nullable: true
          description: 'Per-request correlation id (matches the `requestId` field in

            server logs). Include this when filing support tickets.'
      required:
      - code
      - message
    TopologyRoute:
      title: TopologyRoute
      type: object
      properties:
        source:
          $ref: '#/components/schemas/AssetAddress'
        destination:
          $ref: '#/components/schemas/AssetAddress'
        providers:
          type: array
          items:
            $ref: '#/components/schemas/TopologyRouteProvider'
        lastUsed:
          type: string
          format: date-time
          nullable: true
        totalQuoteCount:
          type: integer
      required:
      - source
      - destination
      - providers
      - totalQuoteCount
    AddressFrequency:
      title: AddressFrequency
      type: object
      properties:
        address:
          type: string
        count:
          type: integer
      required:
      - address
      - count
    TopologyRouteProvider:
      title: TopologyRouteProvider
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Providers'
        lastUsed:
          type: string
          format: date-time
          nullable: true
        quoteCount:
          type: integer
      required:
      - provider
      - quoteCount
    AssetAddress:
      title: AssetAddress
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        address:
          type: string
      required:
      - chain
      - address
    TopologyRouteStats:
      title: TopologyRouteStats
      type: object
      properties:
        totalRoutes:
          type: integer
        activeRoutes:
          type: integer
        collectingSince:
          type: string
          format: date-time
          nullable: true
        lastUpdated:
          type: string
          format: date-time
          nullable: true
        hottestPaths:
          type: array
          items:
            $ref: '#/components/schemas/TopologyRoute'
        topSenders:
          type: array
          items:
            $ref: '#/components/schemas/AddressFrequency'
        topRecipients:
          type: array
          items:
            $ref: '#/components/schemas/AddressFrequency'
      required:
      - totalRoutes
      - activeRoutes
      - hottestPaths
      - topSenders
      - topRecipients
    Providers:
      title: Providers
      type: string
      enum:
      - m-swap-facility
      - m-wormhole-portal
      - m-hyperlane-portal
      - m-portal
      - wormhole-cctp
      - jupiter
      - raydium
      - mayan-swift
      - kyber-swap
      - limit-order
      - uniswap-v3
    ErrorCode:
      title: ErrorCode
      type: string
      enum:
      - QuoteError
      - BadQuoteRequest
      - NoQuotesAvailable
      - BadOrderRequest
      - OrderNotFound
      - OrderNotCancellable
      - CancelOrderError
      - BadTopologyRequest
      - BadPermitRequest
      - PermitNotSupported
      - PermitExpired
      - InvalidPermitSignature
      - PermitQuoteError
      - PermitBuildError
      description: 'Stable machine-readable identifier for an API error. Each value

        corresponds 1:1 to an error type (and to one `responses` entry

        in the OpenAPI spec). Branch on this rather than on the HTTP status

        code — multiple errors may share a status as the API evolves.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key