openapi: 3.2.0 info: title: Ripio WebSocket API version: v4.0 contact: name: Jorn Filho x-logo: url: https://trade-images.ripio.com/general_images/logo-ripio.png href: '#' description: 'Operations tagged WebSocket API across 11 of this provider''s published API definitions: ripio-book-api-openapi.yml, ripio-cryptocurrency-deposits-api-openapi.yml, ripio-cryptocurrency-withdrawals-api-openapi.yml, ripio-general-endpoints-api-openapi.yml, ripio-orders-api-openapi.yml, ripio-public-api-openapi.yml, ripio-ticker-api-openapi.yml, ripio-ticket-api-openapi.yml, ripio-transactions-api-openapi.yml, ripio-user-api-openapi.yml, ripio-wallets-api-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.ripiotrade.co/v4/ tags: - name: WebSocket API paths: {} webhooks: order.create: post: summary: Create Order via WebSocket description: Creates a new trading order via WebSocket API. Supports all order types available in the REST API including limit, market, stop-limit, trailing, ceiling, and iceberg orders. operationId: order.create tags: - WebSocket API requestBody: content: application/json: schema: $ref: '#/components/schemas/WebSocketCreateRequest' examples: limitBuyOrder: summary: Create Limit Buy Order value: id: req-001 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: limit amount: 0.001 price: 100000 external_id: my-order-123 post_only: false expiration: 1723073682 immediate_or_cancel: false fill_or_kill: false limitSellOrder: summary: Create Limit Sell Order value: id: req-002 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: sell type: limit amount: 1 price: 700000 external_id: my-sell-order-456 post_only: false expiration: 1723073682 immediate_or_cancel: false fill_or_kill: false marketBuyOrder: summary: Create Market Buy Order value: id: req-003 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: market amount: 0.1 value: 50000 external_id: market-buy-789 fill_or_kill: false marketSellOrder: summary: Create Market Sell Order value: id: req-004 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: ETH_BRL side: sell type: market amount: 0.1 value: 1000 external_id: market-sell-101 fill_or_kill: false stopLimitBuyOrder: summary: Create Stop Limit Buy Order value: id: req-005 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: stop_limit amount: 1 price: 700000 stop_price: 650000 external_id: stop-buy-202 stopLimitSellOrder: summary: Create Stop Limit Sell Order value: id: req-006 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: sell type: stop_limit amount: 1 price: 700000 stop_price: 750000 external_id: stop-sell-303 trailingBuyOrder: summary: Create Trailing Buy Order value: id: req-007 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: trailing amount: 1 price: 700000 distance: 5000 external_id: trailing-buy-404 trailingSellOrder: summary: Create Trailing Sell Order value: id: req-008 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: sell type: trailing amount: 1 price: 700000 distance: 5000 external_id: trailing-sell-505 ceilingBuyOrder: summary: Create Ceiling Buy Order value: id: req-009 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: ceiling value: 50000 external_id: ceiling-buy-606 fill_or_kill: false ceilingSellOrder: summary: Create Ceiling Sell Order value: id: req-010 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: sell type: ceiling value: 70000 external_id: ceiling-sell-707 fill_or_kill: false icebergBuyOrder: summary: Create Iceberg Buy Order value: id: req-011 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: iceberg amount: 10 step_amount: 1 price: 700000 external_id: iceberg-buy-808 icebergSellOrder: summary: Create Iceberg Sell Order value: id: req-012 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: sell type: iceberg amount: 10 step_amount: 1 price: 700000 external_id: iceberg-sell-909 responses: '200': description: Order created successfully content: application/json: schema: $ref: '#/components/schemas/WebSocketResponse' example: id: req-001 status: 200 result: id: 7155ED34-9EC4-4733-8B32-1E4319CB662F status: open create_date: '2024-03-27T13:27:19.853Z' external_id: my-order-123 pair: BTC_BRL side: buy executed_amount: 0 remaining_amount: 0.001 remaining_value: 100 requested_amount: 0.001 requested_value: 100 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/WebSocketErrorResponse' example: id: req-001 status: 400 result: null error: error_code: 40011 message: Insufficient funds. servers: - url: https://api.ripiotrade.co/v4/ order.cancel: delete: summary: Cancel Order via WebSocket description: Cancels an active trading order via WebSocket API. You can cancel by order ID or external ID. operationId: order.cancel tags: - WebSocket API requestBody: content: application/json: schema: type: object properties: id: type: string description: Unique request identifier for correlation method: type: string enum: - order.cancel description: WebSocket API method params: type: object properties: apiToken: type: string description: API Token for authentication timestamp: type: integer format: int64 description: Timestamp in milliseconds signature: type: string description: HMAC SHA256 signature id: type: string description: Order ID (use either id or external_id, not both) external_id: type: string description: External Order ID (use either id or external_id, not both) required: - apiToken - timestamp - signature required: - id - method - params examples: cancelById: summary: Cancel Order by ID value: id: req-003 method: order.cancel params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature id: 7155ED34-9EC4-4733-8B32-1E4319CB662F cancelByExternalId: summary: Cancel Order by External ID value: id: req-004 method: order.cancel params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature external_id: my-order-123 responses: '200': description: Order canceled successfully content: application/json: schema: $ref: '#/components/schemas/WebSocketCancelResponse' example: id: req-003 status: 200 result: id: 7155ED34-9EC4-4733-8B32-1E4319CB662F create_date: '2024-03-27T13:27:19.853Z' executed_amount: 0 remaining_amount: 0.001 remaining_value: 100 requested_amount: 0.001 status: canceled total_value: 100 type: limit price: 100000 update_date: '2024-03-27T13:30:45.123Z' pair: BTC_BRL external_id: my-order-123 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/WebSocketErrorResponse' example: id: req-003 status: 400 result: null error: error_code: 40020 message: Order already canceled. servers: - url: https://api.ripiotrade.co/v4/ order.update: put: summary: Update Order via WebSocket description: Updates the price and/or amount of an existing active order via WebSocket API. It is not possible to change a canceled or fully executed order. operationId: order.update tags: - WebSocket API requestBody: content: application/json: schema: type: object properties: id: type: string description: Unique request identifier for correlation method: type: string enum: - order.update description: WebSocket API method params: type: object properties: apiToken: type: string description: API Token for authentication timestamp: type: integer format: int64 description: Timestamp in milliseconds signature: type: string description: HMAC SHA256 signature id: type: string description: Order ID to update price: type: string description: New unit price (optional, but at least one of price or amount must be provided) amount: type: string description: New order amount (optional, but at least one of price or amount must be provided) required: - apiToken - timestamp - signature - order_id required: - id - method - params examples: updatePriceAndAmount: summary: Update Order Price and Amount value: id: req-005 method: order.update params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature id: 7155ED34-9EC4-4733-8B32-1E4319CB662F price: '105000' amount: '0.002' updatePriceOnly: summary: Update Order Price Only value: id: req-006 method: order.update params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature id: 7155ED34-9EC4-4733-8B32-1E4319CB662F price: '110000' updateAmountOnly: summary: Update Order Amount Only value: id: req-007 method: order.update params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature id: 7155ED34-9EC4-4733-8B32-1E4319CB662F amount: '0.003' responses: '200': description: Order updated successfully content: application/json: schema: $ref: '#/components/schemas/WebSocketUpdateResponse' example: id: req-005 status: 200 result: null '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/WebSocketErrorResponse' example: id: req-005 status: 400 result: null error: error_code: 40021 message: Order executed completely. servers: - url: https://api.ripiotrade.co/v4/ components: securitySchemes: API_Credentials: type: apiToken in: header name: Authorization description: "You can create API Credentials on: .\n\n After creating the **API Credentials**, you'll need to save in a safe place two pieces of information, an **API Token** and a **Secret Key**. The credentials are required respectively to **Authenticate** and **Sign** all Private REST Requests.\n\n **Attention**: The Secret Key can only be viewed once and cannot be retrieved later. **If you lose the Secret Key, delete the set of credentials and create a new one**. \n\n Each endpoint requires a type of access, which can be `Read`, `Buy/Sell`, `Cryptocurrency withdrawals`, or can contain all of these, each one for its own function. It is possible for the token to be `Read` only, or it may have several types, if it has any other type of access such as: `Buy/Sell` or `Cryptocurrency withdrawals`, it will also be `Read` by default.\n\n\n## Headers\n\n\nFor all private routes, these Headers are required:\n\n| Header | Description |\n|--------------|---------------|\n| **Authorization** | The API Token as a string. |\n| **Timestamp** | A timestamp in milliseconds. See the Timestamp Security section for more details. |\n| **Timestamp-tolerance** | An additional, non-required parameter, that you can send to specify the number of milliseconds after the timestamp for the request to be valid. See the Timestamp Security section for more details. |\n| **Signature** | See the Generating Signature section for more details. |\n\n## Timestamp Security\n\n Timestamp Security is a security method to guarantee the validation of the acceptable time window, in addition to guaranteeing the uniqueness of the request **Signature**.\n\n* **All Private Requests** also require a **Header** parameter, **Timestamp**, which must be the timestamp in milliseconds of when the request was created and sent. Can be generated with `Date.now()` if you're using JavaScript, for example.\n\n* An additional parameter, **Timestamp-tolerance**, non-required, may be sent to specify the max number of milliseconds after the timestamp, that the request is valid. If Timestamp-tolerance is not sent, it defaults to **5000 (5 seconds)**.\n\n* **It is recommended to use a small Timestamp-tolerance of 5000 (5 seconds) or less. The maximum value is 60,000 (60 seconds)**. \n\n## Generating Signature\n\nTo create a signature for all Private Requests, you must **encrypt** the hash-based message using **sha256 HMAC** and encode it in **Base64**. \n\n The **message** must contain:\n\n```\nTimestamp + HTTP Method + Path + JSON Payload\n```\n * Not including the **'+'** sign, just concatenate the content into a string.\n\n* The **Timestamp** is the same as the one sent in the Header.\n\n* For **GET** Requests, it is necessary to consider the **PATH** without **Query Params**. For example, this route: `/withdrawals/estimate-rate/ADA?network=cardano_testnet`. Just `/withdrawals/estimate-fee` is considered. Additionally, the **BODY** is considered an empty **String**.\n\n* **JSON Payload** must be a string and must be the same as the one sent in the request **Body**.\n\n**IMPORTANT:** To prevent an invalid signature, avoid using unnecessary decimal places in the request body properties. For instance, use `1` instead of `1.0`. Alternatively, you can also send numbers as strings in the request body, ensuring they are in the same format but as strings. For example:\n\n```json\n{\n 'amount': '0.01',\n 'pair': 'BTC_BRL',\n 'price': '300000', \n 'side': 'buy', \n 'type': 'limit'\n}\n\n```\n\n### Examples \n\nWe provide functional examples of how to authenticate with this API, written in various programming languages. You can find these examples in our GitHub repository: https://github.com/ripio/api." scopes: Read: Endpoints / token with read access. Buy/Sell: Endpoints / token with Buy and Sell orders access. Crypto Withdrawals: Endpoints / token with Crypto Withdrawals access. Fiat Withdrawals: Endpoints / token with Fiat Withdrawals access. x-refined-from: - ripio-book-api-openapi.yml - ripio-cryptocurrency-deposits-api-openapi.yml - ripio-cryptocurrency-withdrawals-api-openapi.yml - ripio-general-endpoints-api-openapi.yml - ripio-orders-api-openapi.yml - ripio-public-api-openapi.yml - ripio-ticker-api-openapi.yml - ripio-ticket-api-openapi.yml - ripio-transactions-api-openapi.yml - ripio-user-api-openapi.yml - ripio-wallets-api-openapi.yml x-websocket-api: description: "# WebSocket API\n\nThe WebSocket API allows you to perform trading operations (create, cancel, and update orders) via WebSocket connection. This is separate from the WebSocket Stream service which provides real-time market data.\n\n## General API Information\n\n- **Base endpoint**: `wss://ws-api.ripio.com`\n- Connections remain active as long as there is activity; idle connections are disconnected after **60 seconds** of inactivity\n- The WebSocket server will automatically send ping frames to maintain connection health\n- If the WebSocket server does not receive a pong frame back from the connection within **60 seconds**, the connection will be disconnected\n- When you receive a ping, you must send a pong with a copy of ping's payload as soon as possible\n- Unsolicited pong frames are allowed, but will not prevent disconnection\n- Authentication is done using **API Token, Secret, and Timestamp** (same as REST API)\n- All timestamps are in **milliseconds** in UTC\n- All field names and values are **case-sensitive**\n- APIs have a timeout of **10 seconds** when processing a request\n\n## Authentication\n\nThe WebSocket API uses the same authentication mechanism as the REST API, including API Token, Secret, and Timestamp-based signature generation.\n\nFor complete authentication details, including signature generation, please refer to the **Authorization** section.\n\n### Key Points for WebSocket API:\n\n- Use the same **API Token** and **Secret** from your REST API credentials\n- Include `apiToken`, `timestamp`, and `signature` in the `params` object of each request\n- The signature is generated using: **Timestamp + JSON Body (business parameters only)**\n\n### Signature Generation for WebSocket API\n\nUnlike the REST API, the WebSocket signature is simpler because there's no HTTP method or path:\n\n**Message to sign:** `Timestamp + JSON Body`\n\n**Where:**\n- `Timestamp`: The same timestamp sent in the `params.timestamp` field (in milliseconds)\n- `JSON Body`: **ONLY the business parameters** (pair, side, type, amount, price, etc.). **DO NOT include** `apiToken`, `timestamp`, or `signature` in the body to sign.\n\n**Important:** Do NOT include `+` signs - just concatenate the values directly.\n\n### Signature Example\n\n**Request to send:**\n```json\n{\n \"id\": \"req-001\",\n \"method\": \"order.create\",\n \"params\": {\n \"pair\": \"BTC_BRL\",\n \"side\": \"buy\",\n \"type\": \"limit\",\n \"amount\": 0.001,\n \"price\": 100000,\n \"apiToken\": \"your-api-token\",\n \"timestamp\": 1634567890000,\n \"signature\": \"calculated-signature\"\n }\n}\n```\n\n**Body to sign (only business params):**\n```json\n{\n \"pair\": \"BTC_BRL\",\n \"side\": \"buy\",\n \"type\": \"limit\",\n \"amount\": 0.001,\n \"price\": 100000\n}\n```\n\n**Message to sign:**\n```\n1634567890000{\"pair\":\"BTC_BRL\",\"side\":\"buy\",\"type\":\"limit\",\"amount\":0.001,\"price\":100000}\n```\n\n**Then generate HMAC SHA256 signature:**\n```javascript\nconst crypto = require('crypto');\nconst message = timestamp.toString() + JSON.stringify(bodyParams);\nconst signature = crypto.createHmac('sha256', secretKey).update(message).digest('base64');\n```\n\n## Request Format\n\nAll WebSocket API requests must follow this format:\n\n```json\n{\n \"id\": \"unique-request-id\",\n \"method\": \"order.create\",\n \"params\": {\n ...body parameters...,\n \"apiToken\": \"your-api-token\",\n \"timestamp\": 1634567890000,\n \"signature\": \"calculated-signature\"\n }\n}\n```\n\n## Response Format\n\n### Success Response\n\n```json\n{\n \"id\": \"unique-request-id\",\n \"status\": 200,\n \"result\": {\n \"id\": \"7155ED34-9EC4-4733-8B32-1E4319CB662F\",\n \"create_date\": \"2024-03-27T13:27:19.853Z\",\n \"executed_amount\": 0,\n \"external_id\": \"BEAB10B1-45B0-4999-9B2F-D2ED048D6C42\",\n \"pair\": \"BTC_BRL\",\n \"remaining_amount\": 10,\n \"remaining_value\": 1000,\n \"requested_amount\": 10,\n \"requested_value\": 1000,\n \"side\": \"buy\",\n \"status\": \"open\"\n }\n}\n```\n\n### Error Response\n\n```json\n{\n \"id\": \"unique-request-id\",\n \"status\": 400,\n \"result\": null,\n \"error\": {\n \"error_code\": 40011,\n \"message\": \"Insufficient funds.\"\n }\n}\n```" methods: order.create: summary: Create Order via WebSocket description: Creates a new trading order via WebSocket API. Supports all order types available in the REST API including limit, market, stop-limit, trailing, ceiling, and iceberg orders. requestSchema: $ref: '#/components/schemas/WebSocketCreateRequest' responseSchema: $ref: '#/components/schemas/WebSocketResponse' errorSchema: $ref: '#/components/schemas/WebSocketErrorResponse' examples: limitBuyOrder: summary: Create Limit Buy Order value: id: req-001 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: BTC_BRL side: buy type: limit amount: 0.001 price: 100000 external_id: my-order-123 marketSellOrder: summary: Create Market Sell Order value: id: req-002 method: order.create params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature pair: ETH_BRL side: sell type: market amount: 0.1 value: 1000 successResponse: id: req-001 status: 200 result: id: 7155ED34-9EC4-4733-8B32-1E4319CB662F status: open create_date: '2024-03-27T13:27:19.853Z' external_id: my-order-123 pair: BTC_BRL side: buy executed_amount: 0 remaining_amount: 0.001 remaining_value: 100 requested_amount: 0.001 requested_value: 100 order.cancel: summary: Cancel Order via WebSocket description: Cancels an active trading order via WebSocket API. You can cancel by order ID or external ID. requestSchema: type: object properties: id: type: string description: Unique request identifier for correlation method: type: string enum: - order.cancel description: WebSocket API method params: type: object properties: apiToken: type: string description: API Token for authentication timestamp: type: integer format: int64 description: Timestamp in milliseconds signature: type: string description: HMAC SHA256 signature id: type: string description: Order ID (use either id or external_id, not both) external_id: type: string description: External Order ID (use either id or external_id, not both) required: - apiToken - timestamp - signature required: - id - method - params responseSchema: $ref: '#/components/schemas/WebSocketCancelResponse' errorSchema: $ref: '#/components/schemas/WebSocketErrorResponse' examples: cancelById: summary: Cancel Order by ID value: id: req-003 method: order.cancel params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature id: 7155ED34-9EC4-4733-8B32-1E4319CB662F cancelByExternalId: summary: Cancel Order by External ID value: id: req-004 method: order.cancel params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature external_id: my-order-123 successResponse: id: req-003 status: 200 result: id: 7155ED34-9EC4-4733-8B32-1E4319CB662F create_date: '2024-03-27T13:27:19.853Z' executed_amount: 0 remaining_amount: 0.001 remaining_value: 100 requested_amount: 0.001 status: canceled total_value: 100 type: limit price: 100000 update_date: '2024-03-27T13:30:45.123Z' pair: BTC_BRL external_id: my-order-123 order.update: summary: Update Order via WebSocket description: Updates the price and/or amount of an existing active order via WebSocket API. It is not possible to change a canceled or fully executed order. requestSchema: type: object properties: id: type: string description: Unique request identifier for correlation method: type: string enum: - order.update description: WebSocket API method params: type: object properties: apiToken: type: string description: API Token for authentication timestamp: type: integer format: int64 description: Timestamp in milliseconds signature: type: string description: HMAC SHA256 signature order_id: type: string description: Order ID to update price: type: number description: New unit price (optional, but at least one of price or amount must be provided) amount: type: number description: New order amount (optional, but at least one of price or amount must be provided) required: - apiToken - timestamp - signature - order_id required: - id - method - params responseSchema: $ref: '#/components/schemas/WebSocketUpdateResponse' errorSchema: $ref: '#/components/schemas/WebSocketErrorResponse' examples: updatePriceAndAmount: summary: Update Order Price and Amount value: id: req-005 method: order.update params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature order_id: 7155ED34-9EC4-4733-8B32-1E4319CB662F price: 105000 amount: 0.002 updatePriceOnly: summary: Update Order Price Only value: id: req-006 method: order.update params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature order_id: 7155ED34-9EC4-4733-8B32-1E4319CB662F price: 110000 updateAmountOnly: summary: Update Order Amount Only value: id: req-007 method: order.update params: apiToken: your-api-token timestamp: 1634567890000 signature: calculated-signature order_id: 7155ED34-9EC4-4733-8B32-1E4319CB662F amount: 0.003 successResponse: id: req-005 status: 200 result: null