Revolut Balance API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Revolut X Crypto Exchange REST Balance API
  description: "As a Revolut X customer, you can use the Revolut X REST API to streamline your trading experience. \n\nBase URL for all endpoints: https://revx.revolut.com/api/1.0\n\n## API key\n\nTo get started using the Revolut X REST API, you need an API key to include with your requests. \nTo create it, follow the instructions below.\n\n### Generate an Ed25519 key pair\n\nBefore creating your API key in the [Revolut X web app](https://exchange.revolut.com/), you must first generate an Ed25519 key pair.\n\nAn Ed25519 key pair consists of a private key and a public key.\nThe private key is kept secret and used for signing data or authenticating, while the public key can be shared to verify signatures and authenticate access.    \n\nYou can generate this pair using `openssl`.\n\n#### 1. Generate the private key\n\nRun the following command in your terminal:\n\n```sh\nopenssl genpkey -algorithm ed25519 -out private.pem\n```\n\nThis command generates a file named `private.pem`, which contains your private key. \nIt has the following structure:\n\n```sh\n-----BEGIN PRIVATE KEY-----\n{YOUR BASE64-ENCODED PRIVATE KEY}\n-----END PRIVATE KEY-----\n```\n\n:::danger[IMPORTANT: Secure your private key]\nThis is your **private** key, and it will be used for signing requests.\n**Your private key is a secret.** \nNever share it with anyone and never send it as a part of any request.\n:::\n\n#### 2. Generate the public key\n\nNext, generate the public key from your private key:\n\n```sh\nopenssl pkey -in private.pem -pubout -out public.pem\n```\n\nThis command generates a file named `public.pem` with your public key.\nIt has the following structure:\n\n```sh\n-----BEGIN PUBLIC KEY-----\n{YOUR BASE64-ENCODED PUBLIC KEY}\n-----END PUBLIC KEY-----\n```\n\n:::info[About your public key]\nThis is your **public** key.\nIt is not secret, and it is safe to share.\nYou will provide this key to Revolut X so we can verify the requests signed with your matching private key.\n\nWhen you provide it, make sure that you copy all of it, including the `-----BEGIN KEY-----` and `-----END KEY-----` lines.\n:::\n\n### Create your API key\n\nOnce you have your **public key** (the content of `public.pem`), you are ready to create your API key.\n\nGo to the [Revolut X web app](https://exchange.revolut.com/) → **Profile** to complete the setup.    \n\n---\n\n## Authentication headers\n\nThis API uses a custom authentication scheme based on Ed25519 signatures.\nEvery request to the API must include the following headers:\n\n| Header | Description |\n| :--- | :--- |\n| `X-Revx-API-Key` | Your API key (64-character alphanumeric string). |\n| `X-Revx-Timestamp` | The Unix timestamp of the request, provided in **milliseconds**. |\n| `X-Revx-Signature` | The request digest string signed with your **private key**. |\n\n### Signing a request\n\nTo generate the `X-Revx-Signature`, you must sign a specific string constructed from your request data.\n\n#### 1. Construct the message string\n\nThe string to sign is a concatenation of the following values, in this specific order:\n\n1. **Timestamp:** Same value as the `X-Revx-Timestamp` header.\n2. **HTTP Method:** Uppercase (e.g., `GET`, `POST`).\n3. **Request Path:** The path starting from `/api` (e.g., `/api/1.0/orders/active`).\n4. **Query String:** The URL query string if present (e.g., `limit=10`). Do not include the `?`.\n5. **Request Body:** The minified JSON body string, if present.\n\n:::note\nWhen concatenating, do not add any separators (spaces, newlines, or commas) between the fields.\n:::\n\n**Example Message:**\n```text\n1765360896219POST/api/1.0/orders{\"client_order_id\":\"3b364427-1f4f-4f66-9935-86b6fb115d26\",\"symbol\":\"BTC-USD\",\"side\":\"BUY\",\"order_configuration\":{\"limit\":{\"base_size\":\"0.1\",\"price\":\"90000.1\"}}}\n```\n\n#### 2. Sign the message\n\n1.  Sign the constructed string using your **Ed25519 private key**.\n2.  **Base64-encode** the resulting signature.\n3.  Send this value in the `X-Revx-Signature` header.\n\n### Code Examples\n\n<details>\n<summary>Python Example</summary>\n\n```python\nimport base64\nfrom pathlib import Path\nfrom nacl.signing import SigningKey\nfrom cryptography.hazmat.primitives import serialization\nfrom cryptography.hazmat.backends import default_backend\n\n# 1. Load your Private Key\npem_data = Path(\"private.pem\").read_bytes()\nprivate_key_obj = serialization.load_pem_private_key(\n    pem_data,\n    password=None,\n    backend=default_backend()\n)\n\n# Extract raw bytes for PyNaCl\nraw_private = private_key_obj.private_bytes(\n    encoding=serialization.Encoding.Raw,\n    format=serialization.PrivateFormat.Raw,\n    encryption_algorithm=serialization.NoEncryption()\n)\n\n# 2. Prepare the message\ntimestamp = \"1746007718237\"\nmethod = \"GET\"\npath = \"/api/1.0/orders/active\"\nquery = \"status=open&limit=10\"\nbody = \"\" # Empty for GET\n\n# Concatenate without separators\nmessage = f\"{timestamp}{method}{path}{query}{body}\".encode('utf-8')\n\n# 3. Sign and Encode\nsigning_key = SigningKey(raw_private)\nsigned = signing_key.sign(message)\nsignature = base64.b64encode(signed.signature).decode()\n\nprint(f\"X-Revx-Signature: {signature}\")\n```\n</details>\n\n<details>\n<summary>Node.js Example</summary>\n\n```javascript\nconst crypto = require('crypto');\nconst fs = require('fs');\n\n// 1. Load your Private Key\nconst privateKey = fs.readFileSync('private.pem', 'utf8');\n\n// 2. Prepare the message\nconst timestamp = Date.now().toString();\nconst method = 'POST';\nconst path = '/api/1.0/crypto-exchange/orders';\nconst body = JSON.stringify({\n  symbol: \"BTC/USD\",\n  type: \"limit\",\n  side: \"buy\",\n  qty: \"0.005\"\n});\n\n// Concatenate without separators\nconst message = timestamp + method + path + body;\n\n// 3. Sign and Encode\n// Note: Use crypto.sign with null to indicate pure Ed25519 signing (no hashing algorithm)\nconst signatureBuffer = crypto.sign(null, Buffer.from(message), privateKey);\nconst signature = signatureBuffer.toString('base64');\n\nconsole.log(`X-Revx-Timestamp: ${timestamp}`);\nconsole.log(`X-Revx-Signature: ${signature}`);\n```\n</details>\n\n---\n\n## API endpoints\n\nTo see the reference for the specific endpoints and operations of this API, browse the menu on the left."
  contact: {}
servers:
- url: https://revx.revolut.com/api/1.0
  description: Production server (uses live data)
- url: https://revx.revolut.codes/api/1.0
  description: Dev server (uses test data)
security:
- ApiKey: []
tags:
- name: Balance
  description: Get your Revolut X crypto exchange balances, including both crypto and fiat.
paths:
  /balances:
    get:
      tags:
      - Balance
      summary: Get all balances
      operationId: getAllBalances
      description: 'Get crypto exchange account balances for the requesting user.

        The user is resolved by the provided API key.'
      parameters:
      - $ref: '#/components/parameters/XRevxTimestamp'
      - $ref: '#/components/parameters/XRevxSignature'
      responses:
        '200':
          description: 'OK


            The list of available balances.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalance'
              examples:
                AccountBalanceExample:
                  summary: Balances response
                  $ref: '#/components/examples/AccountBalanceExample'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  responses:
    ServerError:
      description: Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Something went wrong!
            error_id: 7d85b5e7-d0f0-4696-b7b5-a300d0d03a5e
            timestamp: 3318215482991
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Forbidden
            error_id: 7d85b5e7-d0f0-4696-b7b5-a300d0d03a5e
            timestamp: 3318215482991
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: API key can only be used for authentication from whitelisted IP
            error_id: 7d85b5e7-d0f0-4696-b7b5-a300d0d03a5e
            timestamp: 3318215482991
    RateLimitExceeded:
      description: Rate Limit Exceeded
      headers:
        Retry-After:
          description: The number of milliseconds to wait before making a new request.
          schema:
            type: integer
            example: 5000
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Rate Limit Exceeded
            error_id: 7d85b5e7-d0f0-4696-b7b5-a300d0d03a5e
            timestamp: 3318215482991
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Request timestamp is in the future
            error_id: 7d85b5e7-d0f0-4696-b7b5-a300d0d03a5e
            timestamp: 3318215482991
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response structure
      required:
      - error_id
      - message
      - timestamp
      properties:
        error_id:
          type: string
          format: uuid
          description: Unique identifier for this specific error occurrence.
        message:
          type: string
          description: Human-readable description of the error.
        timestamp:
          type: integer
          format: int64
          description: The time the error occurred in Unix epoch milliseconds.
    AccountBalanceEntry:
      type: object
      properties:
        currency:
          type: string
          description: Currency.
          example: BTC
        available:
          type: string
          format: decimal
          description: Available (free) funds amount. Returned as a string to prevent rounding errors.
          example: '1000.0000'
        staked:
          type: string
          format: decimal
          description: "Staked funds currently earning rewards. \nReturned as a string to prevent floating-point rounding errors."
          example: '2000.5000'
        reserved:
          type: string
          format: decimal
          description: Reserved (locked) funds amount. Returned as a string to prevent rounding errors.
          example: '234.5000'
        total:
          type: string
          format: decimal
          description: Sum of available, reserved, and staked funds. Returned as a string to avoid floating-point rounding errors.
          example: '1234.5000'
      required:
      - currency
      - available
      - reserved
      - total
      example:
        currency: BTC
        available: '1000.00000000'
        reserved: '234.50000000'
        total: '1234.50000000'
    AccountBalance:
      type: array
      items:
        $ref: '#/components/schemas/AccountBalanceEntry'
  parameters:
    XRevxSignature:
      in: header
      name: X-Revx-Signature
      required: true
      description: "The Ed25519 signature of the request. \nProvided with other authentication headers.\n\n:::tip\nSee **Authentication headers: Signing a request** for details on how to generate this.\n:::"
      schema:
        type: string
        example: 2h/t5o8w+l5s+fjyfA0n/e7j4u5b7h4e+g4k4c8h7a2p6k0g7j1f+w0i2j3k9r0l3s8m5t6r+q1s+o3v/t4x8v5y+w1r+m2t/k3w/j4y+
    XRevxTimestamp:
      in: header
      name: X-Revx-Timestamp
      required: true
      description: "Current timestamp in Unix epoch milliseconds. \nUsed to prevent replay attacks and construct the signature.\nProvided with other authentication headers."
      schema:
        type: integer
        example: 1746007718237
  examples:
    AccountBalanceExample:
      value:
      - currency: BTC
        available: '1.25000000'
        reserved: '0.10000000'
        total: '1.35000000'
      - currency: ETH
        available: '10.00000000'
        reserved: '0.00000000'
        staked: '32.00000000'
        total: '42.00000000'
      - currency: USD
        available: '5400.50'
        reserved: '100.00'
        total: '5500.50'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Revx-API-Key
      description: "The [API key](https://developer.revolut.com/docs/api/revolut-x-crypto-exchange#api-key) obtained from the [Revolut X web app](https://exchange.revolut.com/).\nIt takes the form of a 64-character alphanumeric string, and must be provided with other authentication headers.\n\nA sample API key might look like this: \n```sh\nM1VKFtwB0M9C9QJO7goPlwrOytrJsSNE19txsmpsWIKz7xYu3f8aNucIyynAhYBy\n```\n\nEach API key directly maps to the user account (either Business or Retail)."