Ripio Cryptocurrency Deposits API

openapi: 3.2.0
info:
  title: Ripio Trade - API Documentation Cryptocurrency Deposits 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: Cryptocurrency Deposits
paths:
  /deposits:
    get:
      operationId: GetUserDeposits
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositsResponseV4'
      description: 'Lists the user''s cryptocurrency deposits.


        **Attention:** Due to performance concerns, this endpoint now uses cursor-based pagination. The pagination object currently included in the response is now a placeholder and will be entirely removed as of 2026-06-01. The parameter current_page is also a placeholder and will be removed at the same time. Please update your integration accordingly and refer to the documentation for the correct pagination handling.'
      summary: List Cryptocurrency Deposits
      tags:
      - Cryptocurrency Deposits
      security:
      - API Credentials:
        - Read
      parameters:
      - description: Currency code
        in: query
        name: currency_code
        required: false
        schema:
          type: string
        example: BTC
      - in: query
        name: status
        required: false
        schema:
          $ref: '#/components/schemas/DepositStatusParamV4'
      - in: query
        name: start_date
        required: false
        schema:
          $ref: '#/components/schemas/StartDateNoMinParamV4'
      - in: query
        name: end_date
        required: false
        schema:
          $ref: '#/components/schemas/EndDateNoMinParamV4'
      - in: query
        name: page_size
        required: false
        schema:
          $ref: '#/components/schemas/PageSizeParamV4'
      - in: query
        name: current_page
        required: false
        schema:
          $ref: '#/components/schemas/CurrentPageParamV4'
      - description: Network
        in: query
        name: network
        required: false
        schema:
          type: string
        example: bitcoin
      - description: The `c` parameter is the cursor you should use to fetch the next page of results
        in: query
        name: c
        required: false
        schema:
          type: string
        example: BTC
      x-mcp:
        enabled: true
        name: list_cryptocurrency_deposits
        usage: '- To list user cryptocurrency deposits with filtering options

          - To track deposit history by currency, status, or date range

          - To monitor incoming cryptocurrency transactions and their status'
  /deposits/deposit:
    get:
      operationId: GetUserDeposit
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositResponseV4'
      description: Gets a cryptocurrency deposit.
      summary: Get Cryptocurrency Deposit
      tags:
      - Cryptocurrency Deposits
      security:
      - API Credentials:
        - Read
      parameters:
      - description: Deposit identifier
        in: query
        name: id
        required: false
        schema:
          type: string
        example: 000A650D-F8A5-419A-A4C4-194452345981
      - description: Transaction hash
        in: query
        name: hash
        required: false
        schema:
          type: string
        example: 000A650D-F8A5-419A-A4C4-194452345981
      x-mcp:
        enabled: true
        name: get_cryptocurrency_deposit
        usage: '- To retrieve detailed information about a specific cryptocurrency deposit

          - To check deposit status using deposit ID or transaction hash

          - To get comprehensive deposit data including network and confirmation details'
components:
  schemas:
    PageSizeParamV4:
      type: number
      format: int32
      default: 200
      example: 100
      description: Number of records per page
      maximum: 1000
      minimum: 1
    DepositResponseV4:
      properties:
        data:
          $ref: '#/components/schemas/DepositV4'
          example:
            amount: 2.29999999
            confirmation_date: '2017-10-12T22:40:08.273Z'
            create_date: '2017-10-12T22:40:08.273Z'
            currency_code: BTC
            id: 3D41EEF3-A709-4EE5-BDEE-B6435CAA84C8
            is_internal: false
            hash: 4f87d009d88524e627b60c6fbe4ebe671a99lk9ad72aab17e0963c5fbef118e2
            network: bitcoin
            status: confirmed
        error_code:
          type:
          - number
          - 'null'
          enum:
          - null
          example: null
        message:
          type:
          - string
          - 'null'
          example: null
      required:
      - data
      - error_code
      - message
      type: object
      additionalProperties: false
    PaginationV4:
      properties:
        current_page:
          type: number
          format: double
          description: Current page
        page_size:
          type: number
          format: double
          description: Page size
        registers_count:
          type: number
          format: double
          description: Total number of registers
        total_pages:
          type: number
          format: double
          description: Total number of pages
      required:
      - current_page
      - page_size
      - registers_count
      - total_pages
      type: object
      additionalProperties: false
      example:
        current_page: 1
        registers_count: 21
        total_pages: 1
        page_size: 100
    StartDateNoMinParamV4:
      type: string
      default: '[6 months ago]'
      format: date
      description: Initial date filter in ISO-8601 format
    DepositsDataV4:
      properties:
        deposits:
          items:
            $ref: '#/components/schemas/DepositV4'
          type: array
          example:
          - amount: 2.29999999
            confirmation_date: '2017-10-12T22:40:08.273Z'
            create_date: '2017-10-12T22:40:08.273Z'
            currency_code: BTC
            id: 3D41EEF3-A709-4EE5-BDEE-B6435CAA84C8
            is_internal: false
            hash: 4f87d009d88524e627b60c6fbe4ebe671a99lk9ad72aab17e0963c5fbef118e2
            network: bitcoin
            status: confirmed
          - amount: 2.29999999
            confirmation_date: '2017-10-12T20:06:52.983Z'
            create_date: '2017-10-12T20:06:52.983Z'
            currency_code: BTC
            id: 3011675E-A549-46F3-A70B-0F0B0A01A2D6
            is_internal: false
            hash: 181378774394ec47b9861d9facfcd4d4ea11a447tr82532c654d5ee1306b4857
            network: bitcoin
            status: confirmed
        pagination:
          $ref: '#/components/schemas/PaginationV4'
        nc:
          type:
          - string
          - 'null'
          description: This is the next cursor, use its value with the `c` parameter to retrieve the next page
        pc:
          type:
          - string
          - 'null'
          description: This is the previous cursor, use its value with the `c` parameter to retrieve the previous page
      required:
      - deposits
      - pagination
      type: object
      additionalProperties: false
    DepositStatusParamV4:
      type: string
      enum:
      - confirmation_pending
      - confirmed
      - canceled
      description: Deposit status
    DepositV4:
      properties:
        id:
          type: string
          description: Deposit identifier
        currency_code:
          type: string
          description: Currency code
          example: BTC
        hash:
          type: string
          description: Deposit hash
        amount:
          type: number
          format: double
          description: Amount
        status:
          $ref: '#/components/schemas/DepositStatusParamV4'
        create_date:
          type: string
          description: Datetime of the creation
        confirmation_date:
          type: string
          description: Datetime of the confirmation
        tag:
          type: string
          description: Destination 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
          description: Destination 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
        is_internal:
          type: boolean
          description: If true, indicates that the deposit was sent internally by another exchange user
      required:
      - id
      - currency_code
      - hash
      - amount
      - status
      - create_date
      - confirmation_date
      - is_internal
      type: object
      additionalProperties: false
      example:
        amount: 2.29999999
        confirmation_date: '2017-10-12T22:40:08.273Z'
        create_date: '2017-10-12T22:40:08.273Z'
        currency_code: BTC
        id: 3D41EEF3-A709-4EE5-BDEE-B6435CAA84C8
        is_internal: false
        hash: 4f87d009d88524e627b60c6fbe4ebe671a99lk9ad72aab17e0963c5fbef118e2
        network: bitcoin
        status: confirmed
    CurrentPageParamV4:
      type: number
      format: int32
      default: 1
      example: 3
      description: Page number for pagination
    EndDateNoMinParamV4:
      type: string
      default: '[Current date]'
      format: date
      description: Final date filter in ISO-8601 format
    DepositsResponseV4:
      properties:
        data:
          $ref: '#/components/schemas/DepositsDataV4'
        error_code:
          type:
          - number
          - 'null'
          enum:
          - null
          example: null
        message:
          type:
          - string
          - 'null'
          example: null
      required:
      - data
      - error_code
      - message
      type: object
      additionalProperties: false
  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