Skip to navigation
REST API EndpointsAccounting

Change Demo Balance

View as Markdown

Change the cash balance of a demo account.

Available to: All authenticated users

Environments: Demo

Rate Limit (organization administrators): None

Rate Limit (all other users): One balance change per account per hour, with a max account balance of $50,000

Quickly adjust the simulated cash balance of a demo account in your organization. Use this endpoint to reset a trader’s balance during an evaluation, top up an account before a new challenge phase, or adjust a balance after a practice session when you don’t need the additional control that adjustCash provides.

Warning: This endpoint returns HTTP 200 for successes and business errors. Always check the errorText field in the response body to determine whether the request succeeded or failed.

Difference Between changeDemoBalance and adjustCash

The changeDemoBalance endpoint is available to all traders and has rate limits to protect against abuse. Because adjustCash is restricted to organization administrators with Funds permissions, it supports higher throughput and doesn’t have a rate limit. adjustCash also gives you more control: you can classify the adjustment type, specify the currency, and include an audit comment.

Field Details

The accountId must reference an active demo account within your organization. You can look up account IDs using the Query Builder in the Admin Dashboards or via the /account/list endpoint.

The cashChange value is applied as a change to the current balance (positive values increase the balance and negative values decrease it). The cashChange value must be between -1,000,000 and 1,000,000 (exclusive). The resulting balance cannot exceed $50,000.

If the optional comment field is omitted, the server defaults to “Demo Change”.

Reversing a Change

While you can’t undo a change, you can make another changeDemoBalance call with the opposite cashChange amount.

Common Failure Scenarios

  • Account ID is invalid (must be greater than 0)
  • Balance change requested within one hour of the last change
  • Balance change would cause the total account balance to exceed $50,000
  • cashChange is outside the allowed range (must be between -1,000,000 and 1,000,000, exclusive)
  • comment exceeds 64 characters
  • Demo account is closed or inactive
  • Request sent to the live or replay environment

Error Messages

errorTextTrigger
"Access denied"Called on a non-demo environment (secondary guard)
"Account Id should be greater than 0"accountId is 0 or negative
"Cash Change should be greater than -1000000"cashChange is -1,000,000 or less
"Cash Change should be less than 1000000"cashChange is 1,000,000 or greater
"Comment should be no longer than 64"comment exceeds 64 characters
"Demo account is closed"The account is inactive
"Maximum cash amount in the simulation account must be less than or equal to $50,000"Resulting balance would exceed $50,000
"One change to the simulation cash balance is permitted per hour. Please try again later."Called within one hour of the last change
"This endpoint should be called on demo.tradovateapi.com"Called on the live or replay environment

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
accountIdlongRequired
cashChangedoubleRequired<=1000000
commentstringOptional<=64 characters

Response

CashBalanceSnapshot
errorTextstringOptional<=8192 characters

Non-empty if the request failed

totalCashValuedoubleOptional
totalPnLdoubleOptional
initialMargindoubleOptional
maintenanceMargindoubleOptional
netLiqdoubleOptional
openPnLdoubleOptional
realizedPnLdoubleOptional
weekRealizedPnLdoubleOptional
withdrawalRejectReasonenumOptional
NoData, PendingContactInfoChange
Allowed values:
currencyCashAvailWithdrawalUSDdoubleOptional
netLiqSODdoubleOptional
totalCashValueSODdoubleOptional
cashUSDdoubleOptional
cashSODUSDdoubleOptional
fullInitialMargindoubleOptional
fullInitialMarginSODdoubleOptional
autoLiqLeveldoubleOptional
fundsInTransitUSDdoubleOptional
fundsInTransitAppliedToCashUSDdoubleOptional