Ripio Wallets API

openapi: 3.2.0
info:
  title: Ripio Trade - API Documentation Wallets API
  version: v4.0
  description: Welcome to the Ripio Trade API documentation.
  contact:
    name: Jorn Filho
  x-logo:
    url: https://trade-images.ripio.com/general_images/logo-ripio.png
    href: '#'
servers:
- url: https://api.ripiotrade.co/v4/
tags:
- name: Wallets
  description: API to check addresses of wallets.
paths:
  /wallets/is-internal:
    get:
      operationId: IsInternalWallet
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsInternalWalletResponseV4'
      description: Indicates if a given wallet belongs to Ripio Trade.
      summary: Is internal
      tags:
      - Wallets
      security:
      - API Credentials:
        - Read
      parameters:
      - in: query
        name: address
        required: true
        schema:
          $ref: '#/components/schemas/AddressParamV4'
      - description: Currency code
        in: query
        name: currency_code
        required: false
        schema:
          type: string
        example: BTC
      x-mcp:
        enabled: false
  /wallets:
    get:
      operationId: GetUserWallets
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletResponseV4'
      description: Lists the user's wallets.
      summary: Wallets
      tags:
      - Wallets
      security:
      - API Credentials:
        - Read
      parameters: []
      x-mcp:
        enabled: false
  /wallets/{currency_code}/{network}:
    get:
      operationId: GetUserWalletAndCreateIfNotExists
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserWalletAndCreateIfNotExistsResponseV4'
      description: Get user network's currency address
      summary: Get User Wallet
      tags:
      - Wallets
      security:
      - API Credentials:
        - Read
      parameters:
      - description: Currency code
        in: path
        name: currency_code
        required: true
        schema:
          type: string
        example: BTC
      - description: Network
        in: path
        name: network
        required: true
        schema:
          type: string
        example: bitcoin
      x-mcp:
        enabled: false
components:
  schemas:
    GetUserWalletAndCreateIfNotExistsResponseV4:
      properties:
        data:
          $ref: '#/components/schemas/GetUserWalletAndCreateIfNotExistsV4'
          example:
            address: 3JentmkNdL97VQDtgRMehxPOMS4AveUZJ1
            currency_code: BTC
            tag: null
            memo: null
            network: bitcoin
        error_code:
          type:
          - number
          - 'null'
          enum:
          - null
          example: null
        message:
          type:
          - string
          - 'null'
          example: null
      required:
      - data
      - error_code
      - message
      type: object
      additionalProperties: false
    IsInternalV4:
      properties:
        is_internal:
          type: boolean
          description: Flag that indicates if it's an internal wallet
          format: boolean
      required:
      - is_internal
      type: object
      additionalProperties: false
    WalletResponseDataV4:
      properties:
        address:
          type: string
        currency_code:
          type: string
        memo:
          type:
          - string
          - 'null'
        network:
          type: string
        tag:
          type:
          - string
          - 'null'
      required:
      - address
      - currency_code
      - memo
      - network
      - tag
      type: object
      additionalProperties: false
      example:
      - address: 3JentmkNdL97VQDtgRMehxPOMS4AveUZJ1
        currency_code: BTC
        memo: null
        network: bitcoin
        tag: null
    GetUserWalletAndCreateIfNotExistsV4:
      properties:
        address:
          type: string
          description: Address
        currency_code:
          type: string
          description: Currency code
          example: BTC
        tag:
          type:
          - string
          - 'null'
          description: Address tag - Check the information about this currency in the public currencies endpoint to check if this currency / network needs tag for deposits
        memo:
          type:
          - string
          - 'null'
          description: Address memo - Check the information about this currency in the public currencies endpoint to check if this currency / network needs memo for deposits
        network:
          type: string
          description: Network
      required:
      - address
      - currency_code
      - tag
      - memo
      - network
      type: object
      additionalProperties: false
    IsInternalWalletResponseV4:
      properties:
        data:
          $ref: '#/components/schemas/IsInternalV4'
        error_code:
          type:
          - number
          - 'null'
          enum:
          - null
          example: null
        message:
          type:
          - string
          - 'null'
          example: null
      required:
      - data
      - error_code
      - message
      type: object
      additionalProperties: false
    WalletResponseV4:
      properties:
        data:
          items:
            $ref: '#/components/schemas/WalletResponseDataV4'
          type: array
        error_code:
          type:
          - number
          - 'null'
          enum:
          - null
          example: null
        message:
          type:
          - string
          - 'null'
          example: null
      required:
      - data
      - error_code
      - message
      type: object
      additionalProperties: false
    AddressParamV4:
      type: string
      example: 2MsPTuASaY8QjQmKFWDyHzYxzpASzKpv7YF
      description: Wallet address
  securitySchemes:
    API_Credentials:
      type: apiToken
      in: header
      name: Authorization
      description: "You can create API Credentials on: <https://trade.ripio.com/market/api/token>.\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-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