Documentation Index Fetch the complete documentation index at: https://docs.polymarket.us/llms.txt
Use this file to discover all available pages before exploring further.
The balance ledger records every change to an account’s cash balance, with both before_balance / after_balance and a typed entry_type describing why the balance moved. Use it for cash reconciliation, audit trails, and regulatory reporting.
For real-time push of these same entries, see the Balance Ledger Stream .
Endpoints Method Endpoint Required Scope Description GET/v1/funding/balance-ledgerread:positionsPaginated query of balance ledger entries GET/v1/funding/balance-ledger/downloadread:positionsStreamed CSV download of balance ledger entries
Balance ledger endpoints are scoped under read:positions (not read:funding) to stay consistent with the existing balance-query endpoints (GetAccountBalance, ListAccountBalances). Calls without read:positions fail with 403 Forbidden (REST) / PERMISSION_DENIED (gRPC).
Historical Floor Setting Value Earliest queryable date 2026-05-01T00:00:00Z
The ledger has a hard historical floor of May 1, 2026 (UTC) . Enforcement is defense-in-depth:
start_time is clamped upstream to the floor when the caller asks for earlier data.Entries with update_time before the floor are post-filtered from JSON responses.
Pre-floor entries are not retrievable through this endpoint.
Cross-Firm Access The account in account=firms/{firm}/accounts/{id} must belong to the caller’s firm (extracted from the JWT firm_id claim).
Condition Error Code Account belongs to a different firm PermissionDeniedJWT missing or firm_id absent UnauthenticatedISV credentials not configured at gateway FailedPreconditionUpstream exchange service unavailable Unavailable
LedgerEntryType The balance ledger uses a strict allowlist of entry types. Internal exchange types are suppressed and never reach clients.
Allowed Types Wire Value Name Description 1DEPOSITFunds deposited into the account 2WITHDRAWALFunds withdrawn from the account 3ORDER_EXECUTIONCash impact of a trade execution 4CORRECTIONManual correction 6RESOLUTIONMarket resolution / settlement payout 7MANUAL_ADJUSTMENTAdmin adjustment 10ACCOUNT_PROPERTY_ADJUSTMENTAccount property change 11COMMISSIONTrading fee 16WITHDRAWAL_REJECTIONFailed withdrawal returned to balance 17MANUAL_TRANSFERInternal transfer between accounts 22PENDING_WITHDRAWAL_CREATIONWithdrawal initiated (funds reserved)
Suppressed Types These Internal types are blocked at the gateway and are never returned to clients.
Wire Value Name Reason 5NETTINGInternal 8SECURITY_BALANCE_ADJUSTMENTInternal 9SECURITY_MARK_TO_MARKETInternal 12CONTRACT_EXPIRATIONInternal 13PENDING_CREDIT_ADJUSTMENTInternal 14BEGINNING_OF_DAYInternal 15SECURITY_WITHDRAWALInternal 18AVERAGE_PRICE_TRANSFERInternal 19GIVE_UPInternal 20SYNCHRONIZATIONInternal 21INTERESTInternal 23SETTLEMENT_FEEInternal
Enforcement Surface Behavior Request validation (any endpoint)Requesting a suppressed type in entry_types returns Aborted (HTTP 409). JSON responses (GET /v1/funding/balance-ledger)Suppressed types in upstream responses are silently dropped. CSV downloads (GET /v1/funding/balance-ledger/download)When entry_types is empty, the gateway substitutes the full allowlist before forwarding upstream so suppressed types do not leak in opaque CSV bytes.
Get Balance Ledger GET /v1/funding/balance-ledger?account=firms/ISV-Alice/accounts/alice-trading & currency = USD & start_time = 2026-05-01T00:00:00Z & page_size = 100
Query Parameters Parameter Type Required Description accountstring Yes Fully qualified account name. currencystring No ISO currency code (e.g., USD). Omit for all currencies on the account. start_timeRFC3339 No Inclusive lower bound on update_time. Clamped to 2026-05-01T00:00:00Z. end_timeRFC3339 No Inclusive upper bound on update_time. entry_typesstring[] No Filter by one or more allowlist types. Suppressed types return Aborted (409). symbolstring No Filter by instrument symbol. descriptionstring No Substring filter on the entry description. Maximum 200 Unicode characters (not bytes) ; longer values return InvalidArgument. newest_firstboolean No If true, descending update_time order. Default false. page_sizeinteger No Maximum entries per page. Max 1000 ; values above 1000 return InvalidArgument. page_tokenstring No Pagination token from a previous response’s nextPageToken.
Sample Response { "entries" : [ { "id" : "bl_01HXYZ..." , "account" : "firms/ISV-Alice/accounts/alice-trading" , "currency" : "USD" , "beforeBalance" : "10000.00" , "afterBalance" : "9474.03" , "description" : "Buy 100 @ 525 + commission" , "updateTime" : "2026-05-02T14:30:15.123Z" , "modifiedSecurityId" : "sec_8129" , "entryType" : "ORDER_EXECUTION" , "symbol" : "tec-nfl-sbw-2026-02-08-kc" , "updateBusinessDate" : "2026-05-02" }, { "id" : "bl_01HXYW..." , "account" : "firms/ISV-Alice/accounts/alice-trading" , "currency" : "USD" , "beforeBalance" : "9474.03" , "afterBalance" : "9472.53" , "description" : "Maker fee" , "updateTime" : "2026-05-02T14:30:15.123Z" , "entryType" : "COMMISSION" , "symbol" : "tec-nfl-sbw-2026-02-08-kc" , "updateBusinessDate" : "2026-05-02" } ], "nextPageToken" : "eyJvZmZzZXQiOjEwMH0=" , "eof" : false }
BalanceLedgerEntry Fields Field Type Description idstring Unique entry identifier. accountstring Account this entry belongs to. currencystring ISO currency code. beforeBalancestring Balance immediately before this change (decimal). afterBalancestring Balance immediately after this change (decimal). descriptionstring Human-readable reason for the change. updateTimeRFC3339 Timestamp of the change. modifiedSecurityIdstring Security ID associated with the change, if any. entryTypeLedgerEntryTypeOne of the allowlisted entry types. symbolstring Instrument symbol associated with the change, if any. updateBusinessDatestring Business date in YYYY-MM-DD.
Download Balance Ledger GET /v1/funding/balance-ledger/download?account=firms/ISV-Alice/accounts/alice-trading & currency = USD & start_time = 2026-05-01T00:00:00Z
The download endpoint streams raw CSV bytes from the upstream ledger as a passthrough.
CSV passthrough caveat. Because the body is opaque to the gateway, individual rows cannot be post-filtered. To prevent suppressed types from leaking in CSV bytes, the gateway substitutes the full allowlist for entry_types upstream when the caller leaves it empty.
Empty result sets return a single empty chunk followed by EOF (HTTP 200 with an empty body).
Rate Limits (per firm) Endpoint Rate Burst Effective GET /v1/funding/balance-ledger0.5 req/sec 5 ~30 req/min GET /v1/funding/balance-ledger/download0.0833 req/sec 1 ~5 req/min
Exceeding these limits returns ResourceExhausted (429 Too Many Requests).
Error Codes Error Cause InvalidArgumentMissing account, or description longer than 200 Unicode characters. Aborted (409)Requested a suppressed entry_types value. PermissionDeniedAccount belongs to a different firm. UnauthenticatedMissing JWT or firm_id claim. FailedPreconditionISV credentials not configured. UnavailableUpstream exchange service not connected. ResourceExhaustedPer-firm rate limit exceeded.
See Also
Balance Ledger Stream Real-time gRPC subscription for balance ledger entries
Position Ledger Position changes (quantity, cost, realized P&L)
Funding Transactions Deposit / withdrawal state changes
Authentication Required scopes and OAuth flow
