Merge pull request #125 from BitGo/update-bitgo-api-docs

Update API reference on BitGo Developer Portal

Author: ericcrosson-bitgo

api.yaml

@@ -105,6 +105,11 @@ tags:
 
       The following headers are returned on every request <table> <tr> <td>Header</td><td>Description</td> </tr> <tr> <td>X-Ratelimit-Limit</td><td>Request limit per second</td> </tr> <tr> <td>X-Ratelimit-Remaining</td><td>Remaining number of requests allowed in interval</td> </tr> <tr> <td>X-Ratelimit-Reset</td><td>Duration in milliseconds until the total quota resets</td> </tr> </table>
       The following header is also returned if the response is `429 Too Many Requests` <table> <tr> <td>Header</td><td>Description</td> </tr> <tr> <td>Retry-After</td><td>Duration in seconds of how long to wait before making a new request</td> </tr> </table>
+  - name: Trade WebSocket
+    description: |-
+      Trade WebSocket API to get real-time status updates for market data and trigger messages for:
+      - Order books - Subscribe to a live feed of all outstanding buy and sell orders on the market for specific coins and tokens. Send messages when specific market conditions occur.
+      - Trade orders - Subscribe to live status updates for your trade orders, including individual fills for an order. Send messages when statuses update.
   - name: Staking Request
     description: API to create, retrieve staking requests, and retrieve staking request transactions. A staking request can be of type STAKE or UNSTAKE.
   - name: Staking State Information
@@ -21257,6 +21262,38 @@ paths:
       responses:
         '202':
           description: Acknowledgement that the action was received
+  /api/prime/trading/v1/ws:
+    get:
+      summary: Get WebSocket connection
+      description: Establish a WebSocket connection to get real-time updates for order books and trade orders.
+      operationId: trade.websocket
+      tags:
+        - Trade WebSocket
+      parameters:
+        - in: header
+          name: Authorization
+          required: true
+          schema:
+            type: string
+          description: Bearer token for authorization
+      requestBody:
+        description: Event subscription details
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebSocketSubscription'
+      responses:
+        '101':
+          description: Switching Protocols
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/OrderBooksResponse'
+                  - $ref: '#/components/schemas/TradeOrdersResponse'
+        '403':
+          description: Forbidden - Missing or invalid access token header
   /api/staking/v1/{coin}/wallets/{walletId}/requests:
     post:
       tags:
@@ -41616,6 +41653,47 @@ components:
             - intentType
             - nonce
         - $ref: '#/components/schemas/BaseIntentWithoutNonce'
+    FillUpdated:
+      title: Fill Updated
+      allOf:
+        - $ref: '#/components/schemas/TradeBaseOrder'
+        - type: object
+          properties:
+            cumulativeQuantity:
+              type: string
+              format: decimal
+              description: The cumulative quantity of the fill
+            averagePrice:
+              type: string
+              format: decimal
+              description: The average price of the fill
+            tradeId:
+              type: string
+              description: The ID of the trade
+            fillQuantity:
+              type: string
+              format: decimal
+              description: The quantity of the fill
+            fillPrice:
+              type: string
+              format: decimal
+              description: The price of the fill
+      example:
+        channel: orders
+        time: '2019-04-25T01:02:03.045678Z'
+        accountId: f230fdebfa084ffebc7e00515f54603f
+        orderId: 14db12f5-4d3d-4fd8-8ced-062aa81bb4bc
+        clientOrderId: my-order-1
+        product: TBTC-TUSD*
+        status: opened
+        type: market
+        side: buy
+        quantity: '1.01'
+        cumulativeQuantity: '0.5'
+        averagePrice: '7090.1'
+        tradeId: a6a9ab1b-2947-41b7-b44d-4ce61fca8b92
+        fillQuantity: '0.50'
+        fillPrice: '7090.1'
     FilteringConditions:
       type: object
       description: |
@@ -45657,7 +45735,7 @@ components:
         - $ref: '#/components/schemas/NewTWAPOrderRequest'
         - $ref: '#/components/schemas/NewSteadyPaceOrderRequest'
     NewSteadyPaceOrderRequest:
-      title: SteadyPace
+      title: Steady Pace
       required:
         - product
         - quantity
@@ -45675,7 +45753,7 @@ components:
           description: Product name e.g. BTC-USD
         type:
           type: string
-          description: Must be set to "twap"
+          description: Must be set to "steady_pace"
         fundingType:
           $ref: '#/components/schemas/FundingType'
         side:
@@ -46177,6 +46255,175 @@ components:
         filledQuantity: '0.02457152'
         filledQuoteQuantity: '1000'
         averagePrice: '40697.32'
+    OrderBooksRequest:
+      title: Order Books
+      required:
+        - type
+        - channel
+        - accountId
+        - productId
+      type: object
+      properties:
+        type:
+          type: string
+          description: The event type (e.g. "subscribe" or "unsubscribe")
+        channel:
+          type: string
+          description: The subscription channel (e.g. "level2" for order books)
+        accountId:
+          type: string
+          description: The ID of the account
+        productId:
+          type: string
+          description: The ID of product. (e.g. "TBTC-TUSD*")
+      example:
+        type: subscribe
+        channel: level2
+        accountId: f230fdebfa084ffebc7e00515f54603f
+        productId: TBTC-TUSD*
+    OrderBooksResponse:
+      title: Order Books Response
+      type: object
+      properties:
+        channel:
+          type: string
+          description: The channel name (e.g. "level2").
+        type:
+          type: string
+          description: The type of the response (e.g. "snapshot").
+        product:
+          type: string
+          description: The product name (e.g. "TBTC-TUSD*").
+        time:
+          type: string
+          format: date-time
+          description: The timestamp of the snapshot.
+        bids:
+          type: array
+          description: An array of bid levels [price, size].
+          items:
+            type: array
+            items:
+              type: string
+        asks:
+          type: array
+          description: An array of ask levels [price, size].
+          items:
+            type: array
+            items:
+              type: string
+      example:
+        channel: level2
+        type: snapshot
+        product: TBTC-TUSD*
+        time: '2020-01-01T09:35:26.465Z'
+        bids:
+          - - '7001.10'
+            - '1.5084'
+        asks:
+          - - '7002.55'
+            - '2.7524'
+    OrderCanceled:
+      title: Order Canceled
+      allOf:
+        - $ref: '#/components/schemas/TradeBaseOrder'
+        - type: object
+          properties:
+            cumulativeQuantity:
+              type: string
+              format: decimal
+              description: The cumulative quantity of the fill
+            averagePrice:
+              type: string
+              format: decimal
+              description: The average price of the fill
+      example:
+        channel: orders
+        time: '2019-04-25T01:02:03.045678Z'
+        accountId: f230fdebfa084ffebc7e00515f54603f
+        orderId: 14db12f5-4d3d-4fd8-8ced-062aa81bb4bc
+        clientOrderId: my-order-1
+        product: TBTC-TUSD*
+        status: canceled
+        type: market
+        side: buy
+        quantity: '1.01'
+        cumulativeQuantity: '0.50'
+        averagePrice: '7090.1'
+    OrderCompleted:
+      title: Order Completed
+      allOf:
+        - $ref: '#/components/schemas/TradeBaseOrder'
+        - type: object
+          properties:
+            cumulativeQuantity:
+              type: string
+              format: decimal
+              description: The cumulative quantity of the fill
+            averagePrice:
+              type: string
+              format: decimal
+              description: The average price of the fill
+      example:
+        channel: orders
+        time: '2019-04-25T01:02:03.045678Z'
+        accountId: f230fdebfa084ffebc7e00515f54603f
+        orderId: 14db12f5-4d3d-4fd8-8ced-062aa81bb4bc
+        clientOrderId: my-order-1
+        product: TBTC-TUSD*
+        status: completed
+        type: market
+        side: buy
+        quantity: '1.01'
+        cumulativeQuantity: '1.01'
+        averagePrice: '7090.1'
+    OrderCreated:
+      title: Order Created
+      allOf:
+        - $ref: '#/components/schemas/TradeBaseOrder'
+        - type: object
+      example:
+        channel: orders
+        time: '2019-04-25T01:02:03.045678Z'
+        accountId: f230fdebfa084ffebc7e00515f54603f
+        orderId: 14db12f5-4d3d-4fd8-8ced-062aa81bb4bc
+        clientOrderId: my-order-1
+        product: TBTC-TUSD*
+        status: opened
+        type: market
+        side: buy
+        quantity: '1.01'
+    OrderError:
+      title: Order Error
+      allOf:
+        - $ref: '#/components/schemas/TradeBaseOrder'
+        - type: object
+          properties:
+            cumulativeQuantity:
+              type: string
+              format: decimal
+              description: The cumulative quantity of the fill
+            averagePrice:
+              type: string
+              format: decimal
+              description: The average price of the fill
+            message:
+              type: string
+              description: The error message
+      example:
+        channel: order
+        time: '2019-04-25T01:02:03.045678Z'
+        accountId: f230fdebfa084ffebc7e00515f54603f
+        orderId: 14db12f5-4d3d-4fd8-8ced-062aa81bb4bc
+        clientOrderId: my-order-1
+        product: TBTC-TUSD*
+        status: error
+        message: insufficient fund
+        type: market
+        side: buy
+        quantity: '1.01'
+        cumulativeQuantity: '0.50'
+        averagePrice: '7090.1'
     OrderStatus:
       type: string
       enum:
@@ -51943,7 +52190,6 @@ components:
             - second
             - minute
             - hour
-            - day
         subOrderSize:
           type: string
           description: The size of each sub-order in the SteadyPace order.
@@ -52616,6 +52862,40 @@ components:
               items:
                 $ref: '#/components/schemas/Touchpoint'
         - $ref: '#/components/schemas/PaginatedResults'
+    TradeBaseOrder:
+      type: object
+      properties:
+        channel:
+          type: string
+          description: The channel you are subscribed to (e.g. "orders")
+        time:
+          type: string
+          format: date-time
+        accountId:
+          type: string
+          description: The ID of the account
+        orderId:
+          type: string
+          description: The ID of the order
+        clientOrderId:
+          type: string
+          description: Custom order ID.
+        product:
+          type: string
+          description: Product name e.g. BTC-USD
+        status:
+          type: string
+          description: The status of the order (e.g. "completed")
+        type:
+          type: string
+          description: The type of order (e.g. "market", "limit", "twap")
+        side:
+          type: string
+          description: The side of the order (e.g. "buy", "sell")
+        quantity:
+          type: string
+          format: decimal
+          description: The specified order quantity.
     TradeBaseQuoteInbound:
       title: TradeBaseQuoteInbound
       oneOf:
@@ -52681,6 +52961,35 @@ components:
       required:
         - currency
         - quantity
+    TradeOrdersRequest:
+      title: Trade Orders
+      required:
+        - type
+        - channel
+        - accountId
+      type: object
+      properties:
+        type:
+          type: string
+          description: The event type (e.g. "subscribe" or "unsubscribe")
+        channel:
+          type: string
+          description: The subscription channel (e.g. "orders" for trade orders)
+        accountId:
+          type: string
+          description: The ID of the account
+      example:
+        type: subscribe
+        channel: orders
+        accountId: f230fdebfa084ffebc7e00515f54603f
+    TradeOrdersResponse:
+      title: Trade Orders Response
+      oneOf:
+        - $ref: '#/components/schemas/OrderCreated'
+        - $ref: '#/components/schemas/FillUpdated'
+        - $ref: '#/components/schemas/OrderCompleted'
+        - $ref: '#/components/schemas/OrderCanceled'
+        - $ref: '#/components/schemas/OrderError'
     TradeUser:
       required:
         - email
@@ -59776,6 +60085,10 @@ components:
           required:
             - sharedStakingObjectId
         - $ref: '#/components/schemas/SuiUnstakingIntent'
+    WebSocketSubscription:
+      oneOf:
+        - $ref: '#/components/schemas/OrderBooksRequest'
+        - $ref: '#/components/schemas/TradeOrdersRequest'
     Webhook:
       title: Webhook
       type: object