Articles in this section

Changelog for VALR API

  • Updated
Follow

27 March 2025

  • Added a GET public route /v1/public/risklimit/:currencypair which provides the available leverage options for a requested currency pair.

  • Added a GET to Margin route /v1/margin/leverage/:currencypair which returns the leverage information for a requested subaccount.

  • Added a PUT to the route /v1/margin/leverage/:currencypair which allows the user to update the maximum leverage for a subaccount.

05 March 2025

  • Added a new public route /v1/public/loans/info returning loan info per currency supporting lending
  • Added support for clientMsgId parameter to Account Web Sockets to correlate requests and responses

13 February 2025

  • Added the V2 API / Brokerage Instructions API
  • Added a new MARGIN_INFO event (beta) on the ACCOUNT websocket

5 February 2025

  • Added a new route /v1/wallet/crypto/withdraw/history to retrieve an account's withdrawal history with currency as an optional query parameter. startTime and endTime (ISO 8601) can be used for additional time-based filtering. The existing route /v1/wallet/crypto/:currencyCode/withdraw/history remains functional but is now deprecated.
  • Added a new route /v1/wallet/crypto/deposit/history to retrieve an account's deposit history with currency as an optional query parameter. startTime and endTime (ISO 8601) can be used for additional time-based filtering. The existing route /v1/wallet/crypto/:currencyCode/deposit/history remains functional but is now deprecated.

27 January 2025

  • PUT /v1/orders/modify Modify REPRICE has been added.

 21 January 2025

  • GET /v1/orders/history now returns totalExecutedQuantity
  • GET /v1/orders/history/summary/orderid/:orderId now returns totalExecutedQuantity
  • GET /v1/orders/history/summary/customerorderid/:customerOrderId now returns totalExecutedQuantity

6 January 2025

  • Add a new route /v1/account/tradehistory to get an account's trading history without specifying a currency pair.

9 December 2024

  • POST /v1/account/subaccounts/transfer now returns the transfer ID
  • Transaction history items of type INTERNAL_TRANSFER now includes a transferId field

25 October 2024

  • Add a new route /v1/loans to create a new loan.
  • Add a new route /v1/loans/open to view your open loans.
  • Add a new route /v1/loans/credit-history?currencySymbol=symbol to view previous loans.
  • Add a new route /v1/loans/increase to increase loan amount.
  • Add a new route /v1/loans/rate to update your loan's rate.
  • Add a new route /v1/loans/update-history?currencySymbol=symbol to view the history of your loan updates.
  • Add a new route /v1/loans/unlock to request an unlock and to cancel a request to unlock a loaned amount.
  • Futures limit and market orders now support conditionalOrderData which can be used to add Stop Loss and/or Take Profit orders.
  • Add a new route /v1/orders/conditionals/:currencyPair/history to fetch conditional orders by pair.
  • Add a new route /v1/orders/conditionals/conditional/:currencyPair/orderid/:orderId to fetch conditional orders by pair and an order ID.
  • Add a new route /v1/orders/conditionals/modify to modify conditional orders.

23 October 2024

  • Added Performance Guidelines

18 September 2024

  • Add reduceOnly flag information to limit and market orders.

30 August 2024

  • Order Types route /v1/public/ordertypes now supports the includeInactivePairs query parameter to allow excluding inactive pairs from the result
  • Add rate-limited sample messages to websockets 

16 August 2024

  • Order history route /v1/orders/history now includes statuses filter.
  • Trade history route /v1/account/:currencyPair/tradehistory now includes skip param.
  • Increased rate limits for websocket write requests to match current http rate limits.

07 August 2024

  • Add new websocket order type BATCH_ORDERS

22 July 2024

  • Split Account websocket section into Read and Write.

18 July 2024

  • Add a new route /v1/account/subaccount to rename subaccount labels.

15 July 2024

  • Increased rate limits for Post, Batch and Delete orders.

02 July 2024

  • Added a new route /v1/account/transactionhistory/subaccounts to expose subaccount transaction history.

  • Add a new route /v1/account/subaccount to DELETE subaccounts

26 June 2024

  • Remove wire withdrawals. These are currently not supported.

04 June 2024

  • Added the /v1/conditionals route to enable GET , POST and DELETE take profit and stop loss (conditional) orders for futures positions.
  • Added the following new events on the ACCOUNT websocket for futures trades: ADD_CONDITIONAL_ORDER, REMOVE_CONDITIONAL_ORDER, OPEN_POSITION_UPDATE, REDUCE_POSITION and POSITION_CLOSED
  • Added the ability to place, modify and cancel orders on the ACCOUNT websocket.
  • Added the CANCEL_ON_DISCONNECT event on the ACCOUNTS websocket.
  • Open Orders call now includes allowMargin flag to easily identify open margin orders.
  • Added the currency pair by type public endpoint /v1/public/pairs/:type - to list currency pairs by either Futures or Spot.
  • Exposed the wallet send costs and minimum withdraw amounts for currencies on the public route /v1/public/currencies
  • Refined the descriptions and examples for Limit Only Reprice, Margin Information.
  • Refined the authentication Requirements in Getting Started section.

12 February 2024

  • Added stricter input validation of side and TimeInForce for Limit Orders and Stop Limit Orders.

 

06 December 2023

  • Added a new public route /v1/public/futures/funding/history to expose the Futures funding rate history.

 

05 December 2023

  • Updated per-second rate limits to reflect new limits.
  • Added the positionId field for Futures positions.
  • Added V2 API requests
    • Modify Limit Order (Beta) - /v2/orders/modify
    • Account Margin Information - /v2/margin/status

  • Updated V1 Order History API - v1/orders/history

    • Optional startTime and endTime date filters can now be used.

27 November 2023

  • /v1/public/currencies responses now include the supported and default blockchain network types for deposits and withdrawals, per currency. The network type can also be supplied when creating an address book address.
  • NOTE: Due to the sensitive nature of withdrawals and deposits, providing the network type will become mandatory for all currencies that support more than one network for withdrawals and deposits from 1 April 2024.
  • Updated API's:
    /v1/public/currencies
    /v1/wallet/crypto/:currencyCode/deposit/address
    /v1/wallet/crypto/:currencyCode/deposit/history
    /v1/wallet/crypto/address-book
    /v1/wallet/crypto/address-book/:currencyCode
    /v1/wallet/crypto/:currencyCode/withdraw
    /v1/wallet/crypto/:currencyCode/withdraw/:withdrawId
    /v1/wallet/crypto/:currencyCode/withdraw/history

 

15 November 2023

  • /v1/public/futures/info - which returns contract details of perpetual futures contracts
  • /v1/positions/open - which returns open futures contracts for an account
  • /v1/positions/closed/summary - which returns a summary of closed futures contracts
  • /v1/positions/closed?currencyPair - which returns a detailed view of closed futures contracts per futures pair
  • /v1/positions/history?currencyPair - which returns a history of futures contracts held by an account
  • /v1/positions/funding/history?currencyPair - a history of funding
  • /v1/margin/account/status - to enable an account for Futures trading using the endpoint
  • Added an example of the MARK_PRICE_UPDATE event on the TRADE websocket

 

09 November 2023

  • Added the /v1/orders/modify to modify open and partially filled Limit Orders.
  • Added MODIFY_ORDER_OUTCOME event to the Account Websocket.
  • Updated the OPEN_ORDERS_UPDATE WebSocket event to include the Order Modified status.
  • Added Margin trading to the /v1/orders/limit and /v1/orders/market.
  • Added /v1/public/:currencyPair/markprice/buckets, which returns Mark Price buckets for a given currency pair.
  • Added Limit Order Reprice to /v1/orders/limit.
  • Updated Trade History /v1/account/:currencyPair/tradehistory?limit=10 to include fees and rewards

 

10 October 2023

  • Added per-second rate-limit to /v1/account/subaccounts/transfer

 

18 September 2023

  • Added sequence number calculation to FULL_ORDERBOOK_UPDATE web socket documentation.

 

18 August 2023

  • Added V2 Exchange Buy/Sell API in Alpha.

 

28 July 2023

  • Updated per second rate limits to reflect new limits.

 

14 July 2023

  • Added Staking API

15 May 2023

  • Documented new websocket connections rate limit
  • Updated the /v1/balances request with query parameterexcludeZeroBalances to return non-zero balances only
  • Updated theBALANCE_UPDATE WebSocket event to include the following fields: totalInReference , totalInReferenceWeighted andreferenceCurrency

Updated pre-request script and documentation to support the yourSubAccountId environment variable. This allows impersonating an account with every request.

 

06 March 2023

  • Added a request to link a new fiat bank account
  • Added a request for linked fiat bank account details
  • Added a request to delete a linked fiat bank account
  • Added a request to list all banks supported for fiat withdrawals per currency
  • Added a request to get an auto-buy reference for buying a currency with a fiat deposit

Added a request to list all currencies supported for auto-buy per fiat currency

 


03 March 2023

  • Removed Deposit Instructions for Wire Transfers

25 November 2022

    • Updated rate limits for/v1/batch/ordersand/v1/orders.

 

17 November 2022

    • Added the Caching section.
    • Added thecollateralandcollateralWeightfields to -v1/public/currencieswhich are reserved for future use.
    • AddedmarginTradingAllowedto the/v1/public/pairsendpoint, reserved for future use.
    • Added theMARK_PRICE_UPDATEevent to theTradeWebsocket
    • Updated theBALANCE_UPDATEWebsocket event to include the following fields that are reserved for future use:collateral,collateralWeight,lendReserved,borrowCollateralReserved,borrowedAmount
  • Updated theNEW_ACCOUNT_HISTORY_RECORDWebsocket event to include the following fields that are reserved for future use:collateral,collateralWeight

 

19 August 2022

    • Clarify that per minute and per second rate limits do not interact.
    • Add examples for stop orders to the Exchange Buy/Sell API.
    • Increase subaccount limit to 2000 per main account.

 

18 August 2022

    • Added `/v1/orders` request to cancel all open orders.
  • Added `/v1/orders/:currencyPair` to cancel all open orders for the given currency pair.

 

04 August 2022

    • Increased per second rate limits for /v1/batch/orders and /v1/orders

 

20 July 2022

    • Updated VALR Pay documentation to reflect new ability to send and receive cryptocurrencies in addition to ZAR.

 

11 July 2022

  • Updated per second rate limits to reflect new limits

 

27 June 2022

  • Added per second rate limits to /v1/batch/orders and /v1/orders

 

12 June 2022

    • The Market Summary APIs /v1/public/marketsummary and /v1/public/:currencyPair/marketsummary now return a markPrice field, which is reserved for future use.
    • The Balances API /v1/account/balances now returns the following additional fields, which are reserved for future use.
        • lendReserved
        • borrowReserved
        • borrowedAmount
  • The Simple Buy/Sell Quote API v1/simple/:currencyPair/quote now returns an array of ordersToMatch, which includes price and quantity; if they exist. 

 

9 May 2022

    • The FULL_ORDERBOOK_UPDATE Trade WebSocket stream now returns a Checksum field.

 

8 February 2022

    • Added the FULL_ORDERBOOK_UPDATE Trade WebSocket stream. Please note that this is an alpha feature and may change in ways that are not backwards-compatible. We value any feedback! Please send your feedback to support@valr.com
    • The following APIs now include a "SequenceNumber" field on the returned order book:
        • /public/:currencyPair/orderbook
        • /public/:currencyPair/orderbook/full
        • /marketdata/:currencyPair/orderbook
        • /marketdata/:currencyPair/orderbook/full

 

14 December 2021

    • Added the Wire Transfers API to facilitate USD wire bank accounts deposits and withdrawals. (/v1/wire)
    • Added the VALR Pay API (/v1/pay) for initiating payments, getting payment details and history.
  • Added the Deposit Reference API to enable retrieval of Deposit reference by subaccount.(/v1/fiat/:currencyCode/deposit/reference) 

 

31 October 2021

  • Added the following APIs for interaction with subaccounts:
    • (account/balances/all) - returns all non zero balances for the portfolio.
    • (account/subaccounts) - returns all subaccounts that belong to a primary account.
    • (account/subaccount) - register a new subaccount.
    • (account/subaccounts/transfer) - transfer between subaccounts.
  • Updated the Authentication section to include the X-VALR-SUB-ACCOUNT-ID header for subaccount impersonation.
  • Updated the rate limit for authenticated API calls.

15 September 2021

Added the Current API Key Information API (/account/api-keys/current) which returns the currently authorised API key's information and permissions.


23 August 2021

  • Batch Orders API (Alpha) is now available to batch multiple exchange orders.
23 June 2021
  • Added additional transaction types to transaction history.
    • VALR Pay PAYMENT transaction types including:  PAYMENT_SENT, PAYMENT_RECEIVED, PAYMENT_REVERSED and PAYMENT_REWARD;
    • Off-chain transaction types including: OFF_CHAIN_BLOCKCHAIN_WITHDRAW and OFF_CHAIN_BLOCKCHAIN_DEPOSIT;
    • Auto-buy AUTO_BUY transaction type.
08 February 2021
  • A Stop Limits API (/orders/stop/limit) is now available to place STOP_LOSS_LIMIT and  TAKE _PROFIT_LIMIT  orders.
  • Limit Orders (/orders/limit) POST request now accepts timeInForce as an optional parameter (GTC, FOK, IOC)
  • Time in Force (GTC, FOK, IOC) field is now included in GET responses of the following APIs: 
    • Open Order (/orders/open)
    • Order History (/orders/history)
    • Order Status (/orders/history/detail/*)
  • New order types of: STOP_LOSS_LIMIT and  TAKE_ PROFIT_LIMIT added to applicable Currency Pairs (currently BTCZAR, ETHZAR and XRPZAR) for the following Public APIs:
    • Public Order Types (/public/ordertypes)
    • Public Currency Pairs ( /public/:currencyPair/ ordertypes )\
  • Updated example for Public Currency pairs (/public/pairs) API with fields tickSize and  baseDecima lPlaces  for each traded currency pair.
  • Updated example for for all TransactionId API requests (/account/transactionhistory) with the id field in the response
  • Updated documentation for Trade History API ( /account/:currencyPair/ tradehistory )
  • Updated example for MarketData Trade History API ( /marketdata/:currencyPair/ tradehistory ) with the quoteVolume field.
  •  
02 February 2021
  • The Order API (/orders/open) now includes the following fields in GET responses:
    updatedAt, status, type
  • Updated the Order History APIs (/orders/history) to include the feeCurrency field
  • Updated documentation: Updated the examples for Order History Detail APIs (/orders/history/detail/*) to include the fields:
    executedFee
    executedQuantity
    executedPrice
29 November 2020
  • Crypto withdrawals created (/wallet/crypto/:currencyCode/ withdraw) with more decimals than the number of decimals supported by the currency will be truncated
  • The Currencies list (/public/currencies) now include the following new fields:
    • decimalPlaces
    • withdrawalDecimalPlaces
  • Withdrawal Info (/wallet/crypto/:currencyCode/ withdraw) now includes the following new field:
    • withdrawalDecimalPlaces
  • Trade History for a currency pair (/account/:currencyPair/ tradehistory) can now be filtered by the skip, limit, startTime, endTime and beforeId parameters. This is similar to Transaction History filtering.
6 September 2020
  • Asks & Bids on ZAR Orderbooks: The number of Asks and Bids sent via our Order Book APIs has been increased from 20 each to 40 each.
  • Order History Detail APIs (`/orders/history/detail/*`) now include the following new fields:
    • executedFee
    • executedQuantity
    • executedPrice`
12 July 2020
  • Rate limiting: Rate limit has been updated to 120 calls per 1 minute window. When rate limited, a response code of 429 and a response header of `x-valr-ratelimited: true` will be returned.
    • Example 1: You are allowed to do 120 calls from 10:10:00 to 10:10:59. When the time changes to 10:11:00, the counter will be reset and will start over.
    • Example 2: If the first request comes in at 10:10:30, the counter will be reset at 10:11:00
31 May 2020
  • Separated the API and Website web socket sessions. WebSockets which were connected via the API will no longer be closed when the user logs out of the VALR website.
  • When a `PING` message is received on the Trade WebSocket, a response with `NO_SUBSCRIPTIONS` in the `PONG` will be sent, if the user has not subscribed to any message types.
  • When a user connects and authenticates to the Account WebSocket, all account balances and open orders associated with the user account will be sent in the response. One `BALANCE_UPDATE` message for each asset held and one `OPEN_ORDERS_UPDATE` message containing all open orders on the account, across all order books will be sent.
  • The `BALANCE_UPDATE` web socket message now includes an `updatedAt` field.
  • The REST GET Balances response (`https://api.valr.com/v1/account/balances`) now includes an `updatedAt` field for each asset held.
  • Added the REST GET VALR Status (`https://api.valr.com/v1/public/status`) request which will indicate whether the API is "online" or in "read-only" mode. In "read-only" mode, only GET and OPTIONS requests are accepted. The "read-only" mode is sometimes necessary during maintenance.
  • The `filledPercentage` field on open orders is now accurate to two decimal places.
  • The REST GET Order Book (`https://api.valr.com/v1/marketdata/:currencyPair/orderbook`) response and the REST GET Order Book (Non aggregated) (`https://api.valr.com/v1/marketdata/:currencyPair/orderbook/full`) response now include a `LastChange` field, indicating the timestamp of the last update to the order book.
  • The `AGGREGATED_ORDERBOOK_UPDATE` message on the Trade web socket now includes a `LastChange` field, indicating the timestamp of the last update to the order book.
Please send any and all feedback via email to help@valr.com, we look forward to your comments and continuing to improve our product offering as we drive towards building VALR into a world class exchange.

Related articles