> ## Documentation Index
> Fetch the complete documentation index at: https://perps-api.vooi.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Read a bot's cycles

> Lists the round trips this bot has recorded, newest first, each with the pair it traded, the scan that chose it, the orders it placed and what it earned and cost. Trades, positions and funding are refreshed from the venues at most once a minute before the figures are computed.



## OpenAPI

````yaml https://vooi-api-app.fly.dev/swagger/json get /bots/{id}/cycles
openapi: 3.1.0
info:
  title: VOOI API
  description: Unified perps API
  version: '1.0'
  contact: {}
servers:
  - url: https://perps-api.vooi.io
security: []
tags: []
paths:
  /bots/{id}/cycles:
    get:
      tags:
        - Bots
      summary: Read a bot's cycles
      description: >-
        Lists the round trips this bot has recorded, newest first, each with the
        pair it traded, the scan that chose it, the orders it placed and what it
        earned and cost. Trades, positions and funding are refreshed from the
        venues at most once a minute before the figures are computed.
      operationId: BotController_getBotCycles
      parameters:
        - name: id
          required: true
          in: path
          description: Bot identifier
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            description: Bot identifier
        - name: cursor
          required: false
          in: query
          description: Pass the cursor from the previous page to fetch the next one.
          schema:
            description: Pass the cursor from the previous page to fetch the next one.
            type: string
        - name: limit
          required: false
          in: query
          description: Number of cycles to return per page, from 1 to 100.
          schema:
            default: 20
            description: Number of cycles to return per page, from 1 to 100.
            type: integer
            minimum: 1
            maximum: 100
        - name: phase
          required: false
          in: query
          description: >-
            Filter by one or more phases, repeating the parameter for several:
            closed for the pairs the bot closed, plus aborted for the entries
            that never filled. Keep the same filter on every page of one cursor.
          schema:
            description: >-
              Filter by one or more phases, repeating the parameter for several:
              closed for the pairs the bot closed, plus aborted for the entries
              that never filled. Keep the same filter on every page of one
              cursor.
            anyOf:
              - type: string
                enum:
                  - aborted
                  - closed
                  - closing
                  - holding
                  - opening
              - type: array
                items:
                  type: string
                  enum:
                    - aborted
                    - closed
                    - closing
                    - holding
                    - opening
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotCyclesDto'
        '400':
          description: Wrong cursor
        '404':
          description: Bot not found
      security:
        - bearer: []
components:
  schemas:
    BotCyclesDto:
      type: object
      properties:
        cursor:
          description: >-
            Pass as cursor to fetch the next page, or null when no more pages
            exist.
          type:
            - string
            - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BotCycleDto'
          description: Cycles, newest first.
      required:
        - cursor
        - items
      title: BotCycles
    BotCycleDto:
      type: object
      properties:
        closedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the bot confirmed the pair was gone, or null while the cycle is
            open.
        createdAt:
          description: When the cycle was recorded.
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        economics:
          type: object
          properties:
            complete:
              type: boolean
              description: >-
                Whether these figures have no known accounting gap — not a
                promise that the history is exhaustive; false when the pair was
                closed outside the bot or its entry was never confirmed, an
                order it names is gone, a leg the venue never acknowledged may
                still have filled, trades are still syncing, a fee or realized
                PnL is missing or paid in a token that is not a stablecoin, or
                an open cycle has no position the bot can read as its own.
            feesUsd:
              type: string
              description: Trading fees you paid on the cycle, stablecoin fees only.
            fundingUsd:
              type: string
              description: >-
                Funding you received less funding you paid on both legs, from
                the entry until the cycle closed or, while it is open, until
                now; it can lag the venue by up to an hour.
            netPnlUsd:
              type: string
              description: >-
                Realized PnL less fees, plus funding, plus unrealized PnL while
                the cycle is open.
            notionalHoursUsd:
              type: string
              description: >-
                Entry notional multiplied by the hours the pair was held,
                counted to the close or, while the cycle is open, to now; it is
                zero until the entry fills.
            notionalOpenedUsd:
              type: string
              description: What the entry filled, both legs together.
            partial:
              type: boolean
              description: >-
                Whether the gap behind `complete: false` is here to stay: the
                pair was closed outside the bot or its entry never confirmed, an
                order it names is gone, a fee or funding token is not a
                stablecoin, or the cycle is closed and its figures still have a
                gap after the venues were synced. False while an open cycle is
                only waiting for the next sync.
            realizedPnlUsd:
              type: string
              description: Realized PnL the venues reported on the cycle trades.
            unrealizedPnlUsd:
              type: string
              description: >-
                Unrealized PnL on the legs of an open cycle, and zero once the
                cycle closes.
            volumeUsd:
              type: string
              description: Everything the cycle traded, entry and exit, both legs.
          required:
            - complete
            - feesUsd
            - fundingUsd
            - netPnlUsd
            - notionalHoursUsd
            - notionalOpenedUsd
            - partial
            - realizedPnlUsd
            - unrealizedPnlUsd
            - volumeUsd
          title: BotCycleEconomics
          description: What the cycle earns and costs you.
        entry:
          description: >-
            The scan that chose this pair, with the candidates it beat and what
            was passed over; null when the stored scan no longer matches the
            current schema.
          anyOf:
            - type: object
              properties:
                candidates:
                  type: array
                  items:
                    type: object
                    properties:
                      asset:
                        type: string
                        description: Coin the pair trades, as the scanner names it
                      long:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|vntl|io|hyperliquid)$
                        description: >-
                          Venue the pair would be bought on: the exchange, or
                          `hyperliquid:<dex>` on Hyperliquid
                      short:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|vntl|io|hyperliquid)$
                        description: >-
                          Venue the pair would be sold on: the exchange, or
                          `hyperliquid:<dex>` on Hyperliquid
                      averageSpreadBpsPerHour:
                        description: >-
                          Average funding spread over the last day, in bps per
                          hour; null when unknown
                        type:
                          - number
                          - 'null'
                      entryBasisBps:
                        type: number
                        description: >-
                          Price gap between the two venues' mids at entry,
                          positive when the short leg is dearer
                      expectedNetBps:
                        type: number
                        description: >-
                          Funding expected over the configured hold at the lower
                          of the current and the day-average spread, less the
                          round trip cost
                      feesBps:
                        description: >-
                          Fees for opening and closing the pair at the account's
                          rates, the VOOI fee included, in bps of the notional;
                          part of roundTripCostBps
                        type: number
                      limitLeg:
                        type: string
                        enum:
                          - long
                          - short
                        description: Which leg would rest as a post-only limit
                      longMarketId:
                        description: Market the long leg would trade on its venue
                        type: string
                      longSlippageBps:
                        description: >-
                          Cost of buying the bot's notional across the long
                          venue's book, in bps of mid; null when the scanner has
                          no depth for it
                        type:
                          - number
                          - 'null'
                      roundTripCostBps:
                        type: number
                        description: >-
                          Fees, the hedge's book crossing, the resting leg's
                          bid-ask spread and the entry gap, for opening and
                          closing the pair
                      shortMarketId:
                        description: Market the short leg would trade on its venue
                        type: string
                      shortSlippageBps:
                        description: >-
                          Cost of selling the bot's notional across the short
                          venue's book, in bps of mid; null when the scanner has
                          no depth for it
                        type:
                          - number
                          - 'null'
                      spreadBpsPerHour:
                        type: number
                        description: Funding spread between the two venues, in bps per hour
                    required:
                      - asset
                      - long
                      - short
                      - entryBasisBps
                      - expectedNetBps
                      - limitLeg
                      - roundTripCostBps
                      - spreadBpsPerHour
                    title: BotScanCandidate
                  description: >-
                    The most promising pairs that passed ranking, best first;
                    only the few the bot would try are kept, and `pairs` less
                    the `rejected` counts is how many passed
                nearMisses:
                  default: []
                  description: >-
                    The pairs only the cost cap or only the expected-profit
                    floor refused, the two closest to each limit, the closest
                    first: the cheapest over the cap, the highest expected net
                    under the floor; scans stored before the field have none
                  type: array
                  items:
                    type: object
                    properties:
                      asset:
                        type: string
                        description: Coin the pair trades, as the scanner names it
                      long:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|vntl|io|hyperliquid)$
                        description: >-
                          Venue the pair would be bought on: the exchange, or
                          `hyperliquid:<dex>` on Hyperliquid
                      short:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|vntl|io|hyperliquid)$
                        description: >-
                          Venue the pair would be sold on: the exchange, or
                          `hyperliquid:<dex>` on Hyperliquid
                      averageSpreadBpsPerHour:
                        description: >-
                          Average funding spread over the last day, in bps per
                          hour; null when unknown
                        type:
                          - number
                          - 'null'
                      entryBasisBps:
                        type: number
                        description: >-
                          Price gap between the two venues' mids at entry,
                          positive when the short leg is dearer
                      expectedNetBps:
                        type: number
                        description: >-
                          Funding expected over the configured hold at the lower
                          of the current and the day-average spread, less the
                          round trip cost
                      feesBps:
                        description: >-
                          Fees for opening and closing the pair at the account's
                          rates, the VOOI fee included, in bps of the notional;
                          part of roundTripCostBps
                        type: number
                      limitLeg:
                        type: string
                        enum:
                          - long
                          - short
                        description: Which leg would rest as a post-only limit
                      longMarketId:
                        description: Market the long leg would trade on its venue
                        type: string
                      longSlippageBps:
                        description: >-
                          Cost of buying the bot's notional across the long
                          venue's book, in bps of mid; null when the scanner has
                          no depth for it
                        type:
                          - number
                          - 'null'
                      roundTripCostBps:
                        type: number
                        description: >-
                          Fees, the hedge's book crossing, the resting leg's
                          bid-ask spread and the entry gap, for opening and
                          closing the pair
                      shortMarketId:
                        description: Market the short leg would trade on its venue
                        type: string
                      shortSlippageBps:
                        description: >-
                          Cost of selling the bot's notional across the short
                          venue's book, in bps of mid; null when the scanner has
                          no depth for it
                        type:
                          - number
                          - 'null'
                      spreadBpsPerHour:
                        type: number
                        description: Funding spread between the two venues, in bps per hour
                      reason:
                        type: string
                        enum:
                          - cost_above_cap
                          - expected_net_below_min
                        description: >-
                          cost_above_cap — the round trip costs more than the
                          configured cap; expected_net_below_min — the funding
                          expected over the hold does not clear the round trip
                          by the configured margin
                    required:
                      - asset
                      - long
                      - short
                      - entryBasisBps
                      - expectedNetBps
                      - limitLeg
                      - roundTripCostBps
                      - spreadBpsPerHour
                      - reason
                    title: BotScanNearMiss
                pairs:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                  description: How many pairs the scanner returned
                rejected:
                  type: array
                  items:
                    type: object
                    properties:
                      pairs:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 9007199254740991
                        description: How many pairs this rule dropped
                      reason:
                        type: string
                        enum:
                          - average_not_paying
                          - cost_above_cap
                          - expected_net_below_min
                          - no_entry_basis
                          - no_reverse_pair
                          - no_slippage
                          - not_on_required_venue
                          - spread_not_held
                          - spread_not_held_24h
                          - spread_not_paying
                        description: >-
                          spread_not_paying — funding does not pay in this
                          direction; spread_not_held — the spread has not been
                          positive for as long as the risk level asks, or its
                          history is unknown; average_not_paying — it pays now
                          but paid nothing net over the last day (low and
                          medium); spread_not_held_24h — the spread turned
                          against the pair in the last day (older scans);
                          not_on_required_venue — neither leg is on the pinned
                          venue; no_entry_basis — a venue is not quoting both
                          sides, or its bid is not below its ask; no_slippage —
                          the scanner has no slippage for the hedging leg;
                          cost_above_cap — the round trip costs more than the
                          configured cap; expected_net_below_min — the funding
                          expected over the hold does not clear the round trip
                          by the configured margin; no_reverse_pair — the venues
                          did not quote the pair the other way (older scans)
                    required:
                      - pairs
                      - reason
                    title: BotScanRejection
                  description: What ranking dropped, counted per rule
                scannedAt:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  description: When the scan ran
                skipped:
                  type: array
                  items:
                    type: object
                    properties:
                      asset:
                        type: string
                        description: Coin the pair trades, as the scanner names it
                      long:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|vntl|io|hyperliquid)$
                        description: >-
                          Venue the pair would be bought on: the exchange, or
                          `hyperliquid:<dex>` on Hyperliquid
                      short:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|vntl|io|hyperliquid)$
                        description: >-
                          Venue the pair would be sold on: the exchange, or
                          `hyperliquid:<dex>` on Hyperliquid
                      reason:
                        type: string
                        description: What stopped the bot from opening this pair
                    required:
                      - asset
                      - long
                      - short
                      - reason
                    title: BotScanSkip
                  description: >-
                    Ranked pairs the bot could not open, with what stopped each
                    one
                config:
                  description: Settings the bot entered the pair with
                  type: object
                  properties:
                    categories:
                      description: Asset classes to trade; omit to trade every category
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - commodities
                          - crypto
                          - etf-index
                          - forex
                          - pre-ipo
                          - stocks-asia
                          - stocks-us
                        description: Asset class of the market
                    exchanges:
                      minItems: 2
                      type: array
                      items:
                        anyOf:
                          - type: string
                            enum:
                              - aster
                              - binance
                              - bybit
                              - extended
                              - gate
                              - hyperliquid
                              - lighter
                              - mexc
                              - ondo
                              - robinhood
                            description: Supported perpetual exchange
                          - type: string
                            pattern: ^hyperliquid:(xyz|mkts|io|hyperliquid)$
                      description: >-
                        Venues the pair legs may be opened on: an exchange name
                        for all of its markets, or `hyperliquid:<dex>` for one
                        Hyperliquid dex (`hyperliquid:hyperliquid` for
                        Hyperliquid's own perps, otherwise a HIP-3 dex: `xyz`,
                        `mkts` or `io`); each leg of a pair is on a different
                        one of these, and a bare `hyperliquid` counts as one
                      example:
                        - hyperliquid:io
                        - lighter
                    leverage:
                      type: integer
                      exclusiveMinimum: 0
                      maximum: 9007199254740991
                      description: Leverage per leg, capped by each market limit
                      example: 2
                    maxHoldHours:
                      default: 24
                      description: >-
                        Longest time to hold a pair before closing it even while
                        the spread still pays; low for frequent rolls, high for
                        carry
                      type: number
                      exclusiveMinimum: 0
                    maxRoundTripCostBps:
                      type: number
                      exclusiveMinimum: 0
                      description: >-
                        Most a round trip (entry plus exit: fees, the hedge's
                        book crossing and the resting leg's bid-ask spread) may
                        cost, in basis points of the notional; pairs are ranked
                        by expected funding over the hold minus this cost
                      example: 25
                    minExpectedNetBps:
                      description: >-
                        Least a pair must be expected to earn over the hold
                        after its round trip, in basis points of the notional;
                        omit to enter on the cost cap alone, as points farming
                        does
                      example: 20
                      type: number
                    notionalUsd:
                      type: number
                      exclusiveMinimum: 0
                      description: >-
                        Notional per leg in USD at the full leverage; a pair
                        trades about 5% under it, further under where a venue
                        reserves fee and slippage beyond notionalUsd / leverage
                        (a market leg on Extended, Lighter or Robinhood) or a
                        market caps leverage lower
                      example: 500
                    requiredExchange:
                      description: >-
                        Venue one leg of every pair must be on, an exchange or
                        one Hyperliquid dex as in `exchanges`; omit to let any
                        two venues pair up
                      anyOf:
                        - type: string
                          enum:
                            - aster
                            - binance
                            - bybit
                            - extended
                            - gate
                            - hyperliquid
                            - lighter
                            - mexc
                            - ondo
                            - robinhood
                          description: Supported perpetual exchange
                        - type: string
                          pattern: ^hyperliquid:(xyz|mkts|io|hyperliquid)$
                    risk:
                      default: low
                      type: string
                      enum:
                        - low
                        - medium
                        - high
                      description: >-
                        How much history the bot wants of a pair: low — a spread
                        positive for the last 12 hours that also paid over the
                        last day, held until the day stops paying or the spread
                        flips hard; medium — the same with 6 hours; high — a
                        spread paying now is enough, held until it turns clearly
                        negative
                  required:
                    - exchanges
                    - leverage
                    - maxRoundTripCostBps
                    - notionalUsd
                fees:
                  description: Fee rates the entered pair was priced at
                  type: object
                  properties:
                    long:
                      type: object
                      properties:
                        makerBps:
                          type: number
                          description: >-
                            Fee on a fill that rests on the book, in bps of the
                            fill's notional, VOOI fee included
                        shared:
                          type: boolean
                          description: >-
                            Whether the rates come from the shared fee table
                            rather than the account's own
                        takerBps:
                          type: number
                          description: >-
                            Fee on a fill that takes the book, in bps of the
                            fill's notional, VOOI fee included
                      required:
                        - makerBps
                        - shared
                        - takerBps
                      title: BotLegFees
                      description: Fee rates of the entered pair's long market
                    short:
                      type: object
                      properties:
                        makerBps:
                          type: number
                          description: >-
                            Fee on a fill that rests on the book, in bps of the
                            fill's notional, VOOI fee included
                        shared:
                          type: boolean
                          description: >-
                            Whether the rates come from the shared fee table
                            rather than the account's own
                        takerBps:
                          type: number
                          description: >-
                            Fee on a fill that takes the book, in bps of the
                            fill's notional, VOOI fee included
                      required:
                        - makerBps
                        - shared
                        - takerBps
                      title: BotLegFees
                      description: Fee rates of the entered pair's short market
                  required:
                    - long
                    - short
              required:
                - candidates
                - pairs
                - rejected
                - scannedAt
                - skipped
              title: BotCycleEntry
            - type: 'null'
        entryOrder:
          anyOf:
            - type: object
              properties:
                createdAt:
                  description: When the bot sent the order.
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                finishedAt:
                  anyOf:
                    - type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                    - type: 'null'
                  description: >-
                    When the order stopped working, or null while it is still
                    open.
                id:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  description: Arbitrage order identifier.
                legs:
                  type: array
                  items:
                    type: object
                    properties:
                      exchange:
                        type: string
                        enum:
                          - aster
                          - binance
                          - bybit
                          - extended
                          - gate
                          - hyperliquid
                          - lighter
                          - mexc
                          - ondo
                          - robinhood
                        description: Venue the leg trades on.
                      filledSize:
                        description: >-
                          Base units filled, or null while the venue has not
                          reported a fill.
                        type:
                          - string
                          - 'null'
                      orderId:
                        description: >-
                          Venue order identifier, or null when the venue never
                          acknowledged the leg.
                        type:
                          - string
                          - 'null'
                      price:
                        description: Limit price, or null when the leg crosses at market.
                        type:
                          - string
                          - 'null'
                      side:
                        type: string
                        enum:
                          - buy
                          - sell
                        description: buy or sell, as the leg was sent to the venue.
                      size:
                        type: string
                        description: Base units the leg asks for.
                    required:
                      - exchange
                      - filledSize
                      - orderId
                      - price
                      - side
                      - size
                    title: BotCycleOrderLeg
                  description: The resting leg and the hedging leg.
                status:
                  type: string
                  enum:
                    - canceled
                    - canceling
                    - failed
                    - finished
                    - processing
                  description: >-
                    processing — the order is still working, with the resting
                    leg or its hedge on the way; finished — both legs are done
                    and the order is finalized; canceled — pulled before it
                    finished; failed — needs manual handling, the legs may be
                    directionally exposed.
              required:
                - createdAt
                - finishedAt
                - id
                - legs
                - status
              title: BotCycleOrder
            - type: 'null'
          description: >-
            The order that opened the pair, or null when it is no longer in the
            database.
        exit:
          description: >-
            Why the bot is leaving: spread_flipped (funding turned against the
            pair), max_hold (the configured hold ran out), liquidation_risk (a
            leg came too close to liquidation), external (the pair was closed
            outside the bot), stopped (you stopped the bot and asked it to close
            the pair), unconfirmed (the entry failed without a known fill and
            the venues read flat, so the venue may still hold an order),
            unhedged (a leg was left without its hedge, because the entry hedge
            did not fill or the pair broke while held or closed, so the bot
            closes what is left at market); null until it starts closing.
          anyOf:
            - oneOf:
                - type: object
                  properties:
                    averageSpreadBpsPerHour:
                      description: >-
                        Average funding spread over the last day the exit judged
                        by; null when its risk level judges by the spread alone
                        or the scanner had none
                      type:
                        - number
                        - 'null'
                    reason:
                      type: string
                      description: >-
                        Funding turned against the pair: for low and medium it
                        paid nothing net over the last day or flipped hard, for
                        high it turned clearly negative
                      enum:
                        - spread_flipped
                    spreadBpsPerHour:
                      type: number
                      description: Funding spread when the bot decided to leave
                  required:
                    - reason
                    - spreadBpsPerHour
                - type: object
                  properties:
                    heldHours:
                      type: number
                      description: Hours the pair was held when the hold ran out
                    reason:
                      type: string
                      description: The configured hold ran out
                      enum:
                        - max_hold
                  required:
                    - heldHours
                    - reason
                - type: object
                  properties:
                    consumed:
                      type: number
                      description: >-
                        Share of the leg distance from entry to liquidation that
                        the mark has used
                    exchange:
                      type: string
                      enum:
                        - aster
                        - binance
                        - bybit
                        - extended
                        - gate
                        - hyperliquid
                        - lighter
                        - mexc
                        - ondo
                        - robinhood
                      description: Venue the leg at risk trades on
                    marketId:
                      type: string
                      description: Market the leg at risk trades
                    reason:
                      type: string
                      description: A leg came too close to liquidation
                      enum:
                        - liquidation_risk
                  required:
                    - consumed
                    - exchange
                    - marketId
                    - reason
                - type: object
                  properties:
                    reason:
                      type: string
                      description: The pair was closed outside the bot
                      enum:
                        - external
                  required:
                    - reason
                - type: object
                  properties:
                    problem:
                      description: >-
                        What the hedge venue answered, or what the venues read
                        when the pair broke; null when the hedge ended without
                        an error, as one canceled unfilled does
                      type:
                        - string
                        - 'null'
                    reason:
                      type: string
                      description: >-
                        A leg was left without its hedge, because the entry
                        hedge did not fill after the resting leg had or because
                        the pair broke while held or closed, so the bot closes
                        what is left at market
                      enum:
                        - unhedged
                    rounds:
                      type: integer
                      exclusiveMinimum: 0
                      maximum: 9007199254740991
                      description: >-
                        Rounds of closing what filled with reduce-only market
                        orders so far, one order for each leg still open per
                        round
                    sentAt:
                      type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                      description: When the last round went out
                  required:
                    - problem
                    - reason
                    - rounds
                    - sentAt
                - type: object
                  properties:
                    reason:
                      type: string
                      description: You stopped the bot and asked it to close the pair
                      enum:
                        - stopped
                  required:
                    - reason
                - type: object
                  properties:
                    reason:
                      type: string
                      description: >-
                        The entry order failed without a known fill and the
                        venues read flat; the venue may hold nothing or an order
                        the bot could not see
                      enum:
                        - unconfirmed
                  required:
                    - reason
              title: BotCycleExit
              type: object
            - type: 'null'
        exitOrders:
          type: array
          items:
            type: object
            properties:
              createdAt:
                description: When the bot sent the order.
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
              finishedAt:
                anyOf:
                  - type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  - type: 'null'
                description: >-
                  When the order stopped working, or null while it is still
                  open.
              id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                description: Arbitrage order identifier.
              legs:
                type: array
                items:
                  type: object
                  properties:
                    exchange:
                      type: string
                      enum:
                        - aster
                        - binance
                        - bybit
                        - extended
                        - gate
                        - hyperliquid
                        - lighter
                        - mexc
                        - ondo
                        - robinhood
                      description: Venue the leg trades on.
                    filledSize:
                      description: >-
                        Base units filled, or null while the venue has not
                        reported a fill.
                      type:
                        - string
                        - 'null'
                    orderId:
                      description: >-
                        Venue order identifier, or null when the venue never
                        acknowledged the leg.
                      type:
                        - string
                        - 'null'
                    price:
                      description: Limit price, or null when the leg crosses at market.
                      type:
                        - string
                        - 'null'
                    side:
                      type: string
                      enum:
                        - buy
                        - sell
                      description: buy or sell, as the leg was sent to the venue.
                    size:
                      type: string
                      description: Base units the leg asks for.
                  required:
                    - exchange
                    - filledSize
                    - orderId
                    - price
                    - side
                    - size
                  title: BotCycleOrderLeg
                description: The resting leg and the hedging leg.
              status:
                type: string
                enum:
                  - canceled
                  - canceling
                  - failed
                  - finished
                  - processing
                description: >-
                  processing — the order is still working, with the resting leg
                  or its hedge on the way; finished — both legs are done and the
                  order is finalized; canceled — pulled before it finished;
                  failed — needs manual handling, the legs may be directionally
                  exposed.
            required:
              - createdAt
              - finishedAt
              - id
              - legs
              - status
            title: BotCycleOrder
          description: Every order the bot sent to close the pair, oldest first.
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: Cycle identifier.
        pair:
          anyOf:
            - type: object
              properties:
                asset:
                  type: string
                  description: Coin the pair trades.
                baseQuantity:
                  type: string
                  description: Size of each leg in base units.
                heldFrom:
                  anyOf:
                    - type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                    - type: 'null'
                  description: >-
                    When the entry filled and the hold started; null until the
                    hedge fills, and while the pair is unavailable.
                limitLeg:
                  type: string
                  enum:
                    - long
                    - short
                  description: >-
                    Which leg rests as a post-only limit: long (bought) or short
                    (sold).
                long:
                  type: object
                  properties:
                    baseSymbol:
                      type: string
                      description: Base symbol on this venue
                    exchange:
                      type: string
                      enum:
                        - aster
                        - binance
                        - bybit
                        - extended
                        - gate
                        - hyperliquid
                        - lighter
                        - mexc
                        - ondo
                        - robinhood
                      description: Venue the leg trades on
                    marketId:
                      type: string
                      description: Venue-specific market identifier
                    quoteSymbol:
                      type: string
                      description: Quote symbol on this venue
                    userExchangeId:
                      type: string
                      pattern: ^[1-9]\d*$
                      description: >-
                        Venue account the leg was opened on; it stays the same
                        even if you reconnect the venue.
                  required:
                    - baseSymbol
                    - exchange
                    - marketId
                    - quoteSymbol
                    - userExchangeId
                  title: BotOpenCycleLeg
                  description: Leg the bot bought.
                openedAt:
                  description: When the bot sent the entry order.
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                short:
                  type: object
                  properties:
                    baseSymbol:
                      type: string
                      description: Base symbol on this venue
                    exchange:
                      type: string
                      enum:
                        - aster
                        - binance
                        - bybit
                        - extended
                        - gate
                        - hyperliquid
                        - lighter
                        - mexc
                        - ondo
                        - robinhood
                      description: Venue the leg trades on
                    marketId:
                      type: string
                      description: Venue-specific market identifier
                    quoteSymbol:
                      type: string
                      description: Quote symbol on this venue
                    userExchangeId:
                      type: string
                      pattern: ^[1-9]\d*$
                      description: >-
                        Venue account the leg was opened on; it stays the same
                        even if you reconnect the venue.
                  required:
                    - baseSymbol
                    - exchange
                    - marketId
                    - quoteSymbol
                    - userExchangeId
                  title: BotOpenCycleLeg
                  description: Leg the bot sold.
              required:
                - asset
                - baseQuantity
                - heldFrom
                - limitLeg
                - long
                - openedAt
                - short
              title: BotOpenCyclePair
            - type: 'null'
          description: >-
            The pair itself, read back from the order that opened it; null when
            that order is no longer in the database.
        phase:
          type: string
          enum:
            - aborted
            - closed
            - closing
            - holding
            - opening
          description: >-
            opening — the entry order is working; holding — both legs are open;
            closing — an exit order is working, or the bot is closing what an
            unhedged entry filled; closed — the pair was closed; aborted — the
            entry never filled.
      required:
        - closedAt
        - createdAt
        - economics
        - entry
        - entryOrder
        - exit
        - exitOrders
        - id
        - pair
        - phase
      title: BotCycle
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.