openapi: 3.2.0
info:
  title: Braiins Hashpower Bid orders API
  description: 'Public HTTP API for buying hashrate on the spot market, scheduling fixed-duration

    contracts, and reading account and market data.'
  version: 1.0.0
servers:
- url: https://hashpower.braiins.com/v1
  description: Production public API
security:
- ApiKey: []
tags:
- name: Bid orders
  description: Create, update, cancel, and inspect caller-owned spot-market bids.
paths:
  /spot/bid/current:
    get:
      summary: List user's bids (active)
      description: 'Returns the authenticated caller''s currently active bids. Use the general bid-list endpoint when terminal and historical bids are also needed.


        **Access:** API key required; allowed ACLs: `staff`, `owner`, `read-only`.


        **Rate limit:** 100 requests/minute per API credential.'
      tags:
      - Bid orders
      operationId: spotGetCurrentBids
      x-required-acl:
      - staff
      - owner
      - read-only
      x-rate-limit: 100 requests/minute per API credential
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotGetBidsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
  /spot/bid:
    get:
      summary: List user’s bids (historical & active)
      description: 'Lists caller-owned active and historical bids with optional time, identity, status, and destination filters. Results are ordered by creation time; `reverse=true` changes the order to newest first.


        **Access:** API key required; allowed ACLs: `staff`, `owner`, `read-only`.


        **Rate limit:** 100 requests/minute per API credential.'
      tags:
      - Bid orders
      operationId: spotGetBids
      x-required-acl:
      - staff
      - owner
      - read-only
      x-rate-limit: 100 requests/minute per API credential
      parameters:
      - name: limit
        in: query
        description: Limit amount of rows retrieved. Must be between 1 and 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: offset
        in: query
        description: Offset to start from. Must be >= 0.
        schema:
          $ref: '#/components/schemas/Uint32'
      - name: reverse
        in: query
        description: Reverse (descending) order of results. Default is ascending. Orders are sorted by creation time.
        schema:
          type: boolean
      - name: created_after
        in: query
        description: Filter for orders created on or after YYYY-MM-DD.
        schema:
          type: string
          format: date
          examples:
          - 2025-10-25
      - name: created_before
        in: query
        description: Filter for orders created before YYYY-MM-DD.
        schema:
          type: string
          format: date
          examples:
          - 2025-10-26
      - name: order_id
        in: query
        description: Filter by order ID.
        schema:
          type: string
          examples:
          - B123456789
      - name: bid_status
        in: query
        description: Filter by order status.
        schema:
          $ref: '#/components/schemas/SpotMarketBidStatus'
      - name: exclude_active
        in: query
        description: Exclude current orders.
        schema:
          type: boolean
      - name: upstream_url
        in: query
        description: Filter by upstream URL.
        schema:
          type: string
      - name: upstream_identity
        in: query
        description: Filter by upstream identity.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotGetBidsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
    post:
      summary: Place new bid (buy order) to the market
      description: 'Creates a caller-owned spot buy order. The request is validated against current market settings and account constraints; the response contains the server-assigned public order identifier.


        **Access:** API key required; allowed ACL: `owner`.


        **Rate limit:** 100 requests/minute per API credential.'
      tags:
      - Bid orders
      operationId: spotPlaceBid
      x-required-acl:
      - owner
      x-rate-limit: 100 requests/minute per API credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpotPlaceBidRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
    put:
      summary: Edit existing bid
      description: 'Updates the provided editable fields of a caller-owned bid selected by its public or client-assigned identifier. Omitted fields remain unchanged; market timing and range rules can prevent price or hashrate-limit decreases.


        **Access:** API key required; allowed ACL: `owner`.


        **Rate limit:** 100 requests/minute per API credential.'
      tags:
      - Bid orders
      operationId: spotEditBid
      x-required-acl:
      - owner
      x-rate-limit: 100 requests/minute per API credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpotEditBidRequest'
      responses:
        '200':
          description: Bid updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
    delete:
      summary: Cancel existing bid
      tags:
      - Bid orders
      operationId: spotCancelBid
      description: 'Cancels a caller-owned bid. The JSON body must provide exactly one of `order_id` or `cl_order_id`; cancellation can be rejected while the configured bid grace period is active.


        **Access:** API key required; allowed ACL: `owner`.


        **Rate limit:** 100 requests/minute per API credential.'
      x-required-acl:
      - owner
      x-rate-limit: 100 requests/minute per API credential
      requestBody:
        required: true
        description: Bid selector. Exactly one identifier must be present.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpotCancelBidRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
  /spot/bid/detail/{order_id}:
    get:
      summary: Get detailed information for a specific bid
      tags:
      - Bid orders
      operationId: spotGetBidDetail
      description: 'Retrieves a caller-visible bid including current lifecycle state, accounting counters, configured destination, and network status. The bid must belong to the caller unless the API key has staff access.


        **Access:** API key required; allowed ACLs: `staff`, `owner`, `read-only`.


        **Rate limit:** 100 requests/minute per API credential.'
      x-required-acl:
      - staff
      - owner
      - read-only
      x-rate-limit: 100 requests/minute per API credential
      parameters:
      - name: order_id
        in: path
        required: true
        description: The bid order ID (e.g., B123456789)
        schema:
          type: string
          pattern: ^B[0-9]+$
          examples:
          - B123456789
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotGetBidDetailResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
  /spot/bid/speed/{order_id}:
    get:
      summary: Get bid hashrate history time series
      tags:
      - Bid orders
      operationId: spotGetBidSpeedHistory
      description: 'Returns estimated delivered hashrate samples for a caller-visible bid. `aggregation_period` controls sample buckets and `sliding_window_size` controls the estimator window; use `datetime_from` and `limit` to bound the series.


        **Access:** API key required; allowed ACLs: `staff`, `owner`, `read-only`.


        **Rate limit:** 100 requests/minute per API credential.'
      x-required-acl:
      - staff
      - owner
      - read-only
      x-rate-limit: 100 requests/minute per API credential
      parameters:
      - name: order_id
        in: path
        required: true
        description: The bid order ID (e.g., B123456789)
        schema:
          type: string
          pattern: ^B[0-9]+$
          examples:
          - B123456789
      - name: aggregation_period
        in: query
        description: Aggregation period for resampling the data.
        schema:
          $ref: '#/components/schemas/AggregationPeriod'
      - name: sliding_window_size
        in: query
        description: Sliding window size for estimating hashrate.
        schema:
          $ref: '#/components/schemas/SlidingWindowSize'
      - name: datetime_from
        in: query
        description: Datetime from which to start the history (optional). RFC 3339 format expected.
        schema:
          type: string
          format: date-time
          examples:
          - '2025-10-04T12:00:00Z'
      - name: limit
        in: query
        description: Maximum number of items to return (optional).
        schema:
          $ref: '#/components/schemas/Uint32'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotGetOrderSpeedHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
  /spot/bid/delivery/{order_id}:
    get:
      summary: Get bid delivery history time series
      tags:
      - Bid orders
      operationId: spotGetBidDeliveryHistory
      description: 'Returns purchased, accepted, and rejected shares for a caller-visible bid, grouped by the selected aggregation period. Each value is expressed in millions of shares; use `datetime_from` and `limit` to bound the series.


        **Access:** API key required; allowed ACLs: `staff`, `owner`, `read-only`.


        **Rate limit:** 100 requests/minute per API credential.'
      x-required-acl:
      - staff
      - owner
      - read-only
      x-rate-limit: 100 requests/minute per API credential
      parameters:
      - name: order_id
        in: path
        required: true
        description: The bid order ID (e.g., B123456789)
        schema:
          type: string
          pattern: ^B[0-9]+$
          examples:
          - B123456789
      - name: aggregation_period
        in: query
        description: Aggregation period for resampling the data.
        schema:
          $ref: '#/components/schemas/AggregationPeriod'
      - name: datetime_from
        in: query
        description: Datetime from which to start the history (optional). RFC 3339 format expected.
        schema:
          type: string
          format: date-time
          examples:
          - '2025-10-04T12:00:00Z'
      - name: limit
        in: query
        description: Maximum number of items to return (optional).
        schema:
          $ref: '#/components/schemas/Uint32'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotGetBidDeliveryHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/ServiceError'
components:
  schemas:
    SpotGetBidDeliveryHistoryResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SpotBidDeliveryHistoryItem'
    MultipleStringIds:
      type: object
      required:
      - id
      properties:
        id:
          type: array
          description: Client order IDs for identification.
          items:
            type: string
    SpotMarketBidStatus:
      type: string
      description: Common status values used for multiple client management entities
      enum:
      - BID_STATUS_UNSPECIFIED
      - BID_STATUS_ACTIVE
      - BID_STATUS_PENDING_CANCEL
      - BID_STATUS_CANCELED
      - BID_STATUS_FULFILLED
      - BID_STATUS_PAUSED
      - BID_STATUS_FROZEN
      - BID_STATUS_CREATED
    Uint32:
      type: integer
      format: uint32
      minimum: 0
      maximum: 4294967295
    CancelResponse:
      description: IDs affected by the operation (canceled successfully).
      type: object
      required:
      - affected_ids
      properties:
        affected_ids:
          $ref: '#/components/schemas/MultipleStringIds'
    OptionalDouble:
      description: Optional double value.
      type: object
      properties:
        value:
          $ref: '#/components/schemas/Double'
    SpotMarketBidState:
      type: object
      required:
      - avg_speed_ph
      - progress_pct
      - amount_remaining_sat
      properties:
        avg_speed_ph:
          $ref: '#/components/schemas/Double'
          description: Order hashrate estimate.
        progress_pct:
          type: number
          format: float
          description: Progress in percents (0..100)
        amount_remaining_sat:
          $ref: '#/components/schemas/Double'
          description: Remaining order amount in satoshi.
    SpotCancelBidRequest:
      type: object
      description: Identifies the caller-owned bid to cancel by its public or client-assigned ID.
      oneOf:
      - required:
        - order_id
      - required:
        - cl_order_id
      properties:
        order_id:
          type: string
          description: Server-assigned public bid ID, exclusive with `cl_order_id`.
          pattern: ^B[0-9]+$
          examples:
          - B123456789
        cl_order_id:
          type: string
          description: Client-assigned bid ID, exclusive with `order_id`.
    AggregationPeriod:
      type: string
      description: Aggregation period for bars (OHLCV candles).
      enum:
      - PERIOD_UNSPECIFIED
      - PERIOD_5_MINUTES
      - PERIOD_15_MINUTES
      - PERIOD_1_HOUR
      - PERIOD_4_HOURS
      - PERIOD_1_DAY
    SpotGetBidsResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SpotGetBidsResponseItem'
    SpotGetBidDetailResponse:
      type: object
      required:
      - bid
      - counters_estimate
      - counters_committed
      - state_estimate
      properties:
        bid:
          $ref: '#/components/schemas/SpotMarketBid'
          description: Complete bid information including all metadata
        counters_estimate:
          $ref: '#/components/schemas/SpotMarketBidCounters'
          description: Estimated counters for the bid (may be ahead of committed values)
        counters_committed:
          $ref: '#/components/schemas/SpotMarketBidCounters'
          description: Committed counters for the bid (confirmed values)
        state_estimate:
          $ref: '#/components/schemas/SpotMarketBidState'
          description: Current estimated state of the bid including hashrate and progress
        last_network_failure:
          description: Last network failure related to the bid, if any. For bids with external destinations only.
          $ref: '#/components/schemas/UpstreamFailure'
        history:
          type: array
          description: History of bid status changes and updates
          items:
            $ref: '#/components/schemas/SpotBidHistoryItem'
    SpotEditBidRequest:
      type: object
      oneOf:
      - required:
        - bid_id
      - required:
        - cl_order_id
      properties:
        bid_id:
          type: string
          description: Bid ID (exclusive with cl_order_id).
        cl_order_id:
          type: string
          description: Client assigned ID of this bid for identification (exclusive with bid_id).
        new_amount_sat:
          $ref: '#/components/schemas/Double'
          description: New order amount (total). If provided, it must be greater than previous amount value.
        new_price_sat:
          $ref: '#/components/schemas/Double'
          description: New bid price in satoshi.
        new_speed_limit_ph:
          $ref: '#/components/schemas/OptionalDouble'
          description: New hashrate limit in PH/s. Set to 0 to disable. If omitted, the hashrate limit is unchanged.
        memo:
          type: string
          description: Remark (optional).
    PlaceOrderResponse:
      type: object
      required:
      - id
      - cl_order_id
      properties:
        id:
          type: string
          description: Autogenerated order ID.
        cl_order_id:
          type: string
          description: Client order ID passed through.
    UpstreamFailure:
      type: object
      required:
      - timestamp
      - description
      - code
      properties:
        timestamp:
          type: string
          description: Timestamp of the failure.
        description:
          type: string
          description: Failure description in English.
        code:
          type: string
          description: Failure code (E_ERR_SOME_FAILURE).
    SpotMarketBid:
      type: object
      required:
      - id
      - cl_order_id
      - client_name
      - subaccount
      - dest_upstream
      - speed_limit_ph
      - amount_sat
      - price_sat
      - status
      - is_current
      - memo
      - created
      - created_by
      - last_updated
      - last_updated_by
      - last_paused
      - last_pause_reason
      - fee_rate_pct
      properties:
        id:
          type: string
          description: ID of this bid (autogenerated). 64bit integer prefixes with "B".
        cl_order_id:
          type: string
          description: Client assigned ID of this bid, optional.
        client_name:
          type: string
          description: Client owning this bid.
        subaccount:
          type: string
          description: Subaccount owning this order.
        dest_upstream:
          $ref: '#/components/schemas/UpstreamSpecification'
          description: Upstream specification for orders of dest type UPSTREAM
        speed_limit_ph:
          $ref: '#/components/schemas/Double'
          description: Optional hashrate limit in PH/s.
        amount_sat:
          $ref: '#/components/schemas/Double'
          description: Order amount in satoshi.
        price_sat:
          $ref: '#/components/schemas/Double'
          description: Bid price specified in satoshi.
        status:
          $ref: '#/components/schemas/SpotMarketBidStatus'
          description: This bid's status.
        is_current:
          type: boolean
          description: True if status is not terminal.
        memo:
          type: string
          description: Remark.
        created:
          type: string
          format: date-time
        created_by:
          $ref: '#/components/schemas/ProfileIdentifier'
          description: Profile which created this bid.
        last_updated:
          type: string
          format: date-time
          description: Timestamp of the last user update.
        last_updated_by:
          $ref: '#/components/schemas/ProfileIdentifier'
          description: Profile which updated this bid last time.
        last_paused:
          type: string
          format: date-time
        last_pause_reason:
          type: string
        fee_rate_pct:
          $ref: '#/components/schemas/Double'
          description: Continuous spot buy fee rate in percents.
        is_degraded:
          type: boolean
          description: If true, the bid is in degraded mode because of delivery problems.
        degraded_speed_limit_ph:
          $ref: '#/components/schemas/Double'
          description: Hashrate limit applied during degradation, in PH/s.
        degraded_since:
          type: string
          format: date-time
          description: Timestamp since when the bid has been degraded.
        degradation_reason:
          type: string
          description: Reason for degradation.
    ProfileIdentifier:
      type: object
      required:
      - profile_name
      - client_name
      properties:
        profile_name:
          type: string
        client_name:
          type: string
    SpotGetOrderSpeedHistoryResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SpotGetOrderSpeedHistoryItem'
    SpotBidHistoryItem:
      type: object
      required:
      - timestamp
      - speed_limit_ph
      - price_sat
      - amount
      - status
      - remark
      - updated_by
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the status change or update
        speed_limit_ph:
          $ref: '#/components/schemas/Double'
          description: Hashrate limit in PH/s at the time of this update
        price_sat:
          $ref: '#/components/schemas/Double'
          description: Bid price in satoshi at the time of this update
        amount:
          $ref: '#/components/schemas/Double'
          description: Allocated amount in satoshi at the time of this update
        status:
          $ref: '#/components/schemas/SpotMarketBidStatus'
          description: Bid status at this point in history
        remark:
          type: string
          description: Remark or reason for the status change
        updated_by:
          $ref: '#/components/schemas/ProfileIdentifier'
          description: Profile that made this update
    Double:
      type: number
      format: double
    UpstreamSpecification:
      type: object
      required:
      - url
      - identity
      properties:
        url:
          type: string
          description: Upstream URL
          examples:
          - stratum+tcp://pool.net:7770
        identity:
          type: string
          description: User / worker identification
    SpotGetOrderSpeedHistoryItem:
      type: object
      required:
      - timestamp
      - speed_ph
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the hashrate measurement.
        speed_ph:
          $ref: '#/components/schemas/Double'
          description: Estimated hashrate in PH/s.
    SpotPlaceBidRequest:
      type: object
      required:
      - dest_upstream
      - amount_sat
      - price_sat
      properties:
        cl_order_id:
          type: string
          description: Client assigned ID of this bid, optional.
        dest_upstream:
          $ref: '#/components/schemas/UpstreamSpecification'
          description: Upstream specification for orders of dest type UPSTREAM
        speed_limit_ph:
          $ref: '#/components/schemas/Double'
          description: Optional hashrate limit in PH/s.
        amount_sat:
          $ref: '#/components/schemas/Double'
          description: Order amount in satoshi.
        price_sat:
          $ref: '#/components/schemas/Double'
          description: Bid price specified in satoshi.
        memo:
          type: string
          description: Remark (optional).
    SpotBidDeliveryHistoryItem:
      type: object
      required:
      - timestamp
      - shares_purchased_m
      - shares_accepted_m
      - shares_rejected_m
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the delivery record.
        shares_purchased_m:
          $ref: '#/components/schemas/Double'
          description: Shares purchased (validated by platform). In millions.
        shares_accepted_m:
          $ref: '#/components/schemas/Double'
          description: Shares accepted by the target. In millions.
        shares_rejected_m:
          $ref: '#/components/schemas/Double'
          description: Shares rejected by the target. In millions.
    SlidingWindowSize:
      type: string
      description: Sliding window size for estimating hashrate.
      enum:
      - WINDOW_SIZE_UNSPECIFIED
      - WINDOW_SIZE_10_MINUTES
      - WINDOW_SIZE_20_MINUTES
      - WINDOW_SIZE_30_MINUTES
    SpotMarketBidCounters:
      type: object
      required:
      - shares_purchased_m
      - shares_accepted_m
      - shares_rejected_m
      - fee_paid_sat
      - amount_consumed_sat
      properties:
        shares_purchased_m:
          $ref: '#/components/schemas/Double'
          description: Shares already purchased by this bid. In millions.
        shares_accepted_m:
          $ref: '#/components/schemas/Double'
          description: Shares accepted by bid's target. In millions.
        shares_rejected_m:
          $ref: '#/components/schemas/Double'
          description: Shares rejected by bid's target. In millions.
        fee_paid_sat:
          $ref: '#/components/schemas/Double'
          description: Fees paid in total on this bid. In satoshi.
        amount_consumed_sat:
          $ref: '#/components/schemas/Double'
          description: Consumed order amount in satoshi.
    SpotGetBidsResponseItem:
      type: object
      required:
      - bid
      - counters_estimate
      - counters_committed
      - state_estimate
      properties:
        bid:
          $ref: '#/components/schemas/SpotMarketBid'
        counters_estimate:
          $ref: '#/components/schemas/SpotMarketBidCounters'
        counters_committed:
          $ref: '#/components/schemas/SpotMarketBidCounters'
        state_estimate:
          $ref: '#/components/schemas/SpotMarketBidState'
        last_network_failure:
          description: Last network failure (if any).
          $ref: '#/components/schemas/UpstreamFailure'
  responses:
    ServiceError:
      description: The gateway or upstream service could not complete the request. The response body and status depend on the failing boundary.
    Unauthorized:
      description: The `apikey` header is missing or does not contain a valid API credential.
    TooManyRequests:
      description: The applicable per-credential or per-client-IP request limit was exceeded. Retry after reducing request frequency.
    NotFound:
      description: The requested caller-visible resource does not exist.
    BadRequest:
      description: The path, query, or JSON body is invalid, violates a market rule, or contains mutually exclusive fields.
    Forbidden:
      description: The API credential is valid but its ACL role or resource ownership does not permit this operation.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: apikey
      description: API credential issued for a Braiins Hashpower account. The credential's ACL role and resource ownership determine which authenticated operations and records are available.