Account Snapshot, Balances, and Activity API Reference

The account endpoints give you a complete view of your Bravado integration: who owns it, what wallets are associated, which API scopes are active, how much collateral you hold, and a full timeline of on-chain and trading activity. You can also provision partner-scoped sub-users for white-label flows directly from this surface.

GET /v2/trade/account

Returns a snapshot of your account configuration, including the partner that owns the API key, the wallet addresses Bravado manages for you, and the permissions granted to the current key.

Response

object

The partner entity that owns this integration.

Show partner fields

string

Unique partner ID.

string

URL-safe partner identifier.

string

Human-readable partner name shown in the Bravado dashboard.

object

The user binding associating your API key with a specific Bravado user account.

Show binding fields

string

Internal binding ID.

string

Your own user reference string as supplied during provisioning.

string

Bravado-assigned user ID for this binding.

object

Metadata about the API key used in this request.

Show api_key fields

string

API key ID.

array

List of permission scopes granted, e.g. ["trade.read", "trade.execute", "trade.withdraw"].

number

Maximum requests per minute allowed on this key.

string

Last 4 characters of the key value, for identification.

string

If set, this builder code is used on all orders placed with this key, overriding any value in the request body.

object

The on-chain wallet addresses associated with this account.

Show wallet fields

string

Externally Owned Account address controlled by Bravado’s signing key.

string

Gnosis Safe (proxy wallet) address where collateral and positions are held.

string

The effective builder code that will be used on orders. Reflects any builder_code_override on the key, falling back to the partner default.

string

Maximum open notional exposure in USDC allowed by the partner configuration. null means uncapped.

string

COMPLETE when the account is fully set up and ready to trade. Other values indicate a pending step (e.g. PENDING_WALLET).

Example response

{
  "partner": {
    "id": "partner_abc123",
    "slug": "my-trading-app",
    "display_name": "My Trading App"
  },
  "binding": {
    "id": "binding_xyz789",
    "partner_user_id": "user-001",
    "bravado_user_id": "bvd_user_456def"
  },
  "api_key": {
    "id": "key_ghi012",
    "scopes": ["trade.read", "trade.execute"],
    "rate_limit_per_min": 300,
    "last4": "7k9z",
    "builder_code_override": null
  },
  "wallet": {
    "eoa_address": "0xEOA...aabbcc",
    "safe_address": "0xSafe...ddeeff"
  },
  "builder_code_resolved": "bravado-default",
  "notional_cap_usdc": "50000.00",
  "onboarding_status": "COMPLETE"
}

GET /v2/trade/balances

Returns your current collateral balances in pUSD and USDC.e, along with a combined total and the timestamp of the snapshot.

Response

string

pUSD balance as a decimal string. pUSD is the primary collateral for V2 CLOB trading on Polymarket.

string

Bridged USDC.e balance as a decimal string. This is legacy collateral; you may want to convert it to pUSD via the CLOB or a split/merge workflow.

string

Sum of pUSD and USDC.e expressed in USD-equivalent terms.

number

Unix timestamp (seconds) when the balance snapshot was taken.

Example response

{
  "pusd": "1250.75",
  "usdc_e": "0.00",
  "total_collateral_equivalent": "1250.75",
  "as_of": 1736942400
}

pUSD is the V2 active collateral accepted by the Polymarket CLOB. If you hold a USDC.e balance, you can deposit pUSD to replace it; new orders require pUSD.

GET /v2/trade/balances/withdrawable

Returns all ERC20 token balances in your deposit wallet that are available for withdrawal. Use the token address from this response as the token field in POST /v2/trade/withdraw to move a specific asset.

Response

array

All ERC20 tokens with a non-zero balance in your deposit wallet.

Show balance fields

string

ERC20 contract address on Polygon. Pass this to /withdraw to move this asset.

string

Token symbol, e.g. "pUSD", "USDC.e", "WMATIC".

number

Token decimal places (e.g. 6 for pUSD/USDC).

string

Raw on-chain balance in base units as a string.

string

Estimated USD value of this balance.

Example response

{
  "balances": [
    {
      "token": "0xpUSDcontract...1111",
      "symbol": "pUSD",
      "decimals": 6,
      "balance": "1250750000",
      "value_usd": "1250.75"
    },
    {
      "token": "0xUSDCeContract...2222",
      "symbol": "USDC.e",
      "decimals": 6,
      "balance": "0",
      "value_usd": "0.00"
    }
  ]
}

GET /v2/trade/activity

Returns a paginated timeline of all account activity including trades, on-chain operations, and reward events. Use next_cursor for forward pagination.

Query parameters

string

number

Number of records to return per page. Maximum 200.

string

Opaque pagination cursor from a previous response’s next_cursor. Omit to start from the most recent activity.

Response

array

Ordered list of activity records, newest first.

Show activity fields

string

Activity type (see query parameter values above).

string

ISO 8601 timestamp of the activity.

string

Polygon transaction hash for on-chain activities. null for off-chain events (e.g. MAKER_REBATE).

object

Market context for trade and position activities.

Show market fields

string

Market title.

string

Polymarket URL slug.

string

Condition ID.

string

Outcome label (e.g. "Yes").

string

URL of the market’s icon image.

string

"buy" or "sell" for trade activities. null for non-trade events.

string

Fill price as a decimal probability. Present for TRADE_BUY and TRADE_SELL.

string

Number of shares involved. Present for trade and position activities.

string

Dollar value of the activity (spend, payout, rebate, etc.).

string

Source asset symbol for conversion/deposit activities.

string

Destination asset symbol for conversion/deposit activities.

string

Opaque cursor string to pass as ?cursor= in your next request to retrieve the following page. null when you have reached the end of the timeline.

Example response

{
  "activities": [
    {
      "type": "TRADE_BUY",
      "timestamp": "2025-01-15T12:34:56Z",
      "transaction_hash": "0xtrade...hash01",
      "market": {
        "title": "Will the Fed cut rates in Q1 2025?",
        "slug": "fed-rate-cut-q1-2025",
        "condition_id": "0xcondition...001",
        "outcome": "Yes",
        "icon": "https://polymarket.com/icons/fed.png"
      },
      "side": "buy",
      "price": "0.65",
      "shares": "200",
      "amount_usdc": "130.00",
      "from_asset": null,
      "to_asset": null
    },
    {
      "type": "MAKER_REBATE",
      "timestamp": "2025-01-15T12:34:58Z",
      "transaction_hash": null,
      "market": null,
      "side": null,
      "price": null,
      "shares": null,
      "amount_usdc": "0.02",
      "from_asset": null,
      "to_asset": null
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjJ9"
}

POST /v2/trade/users

Provisions a new partner-scoped user for white-label integrations. Each user gets their own Bravado account with a dedicated Safe proxy wallet, allowing you to manage isolated balances and positions per end user. The call is idempotent on the combination of (partner_id, partner_user_id).

This endpoint requires a master API key with no fixed user binding. It cannot be called with a user-bound key. Contact your Bravado integration manager to obtain a master key.

Required headers

Header	Value
`Authorization`	`Bearer <master_token>`
`Idempotency-Key`	Unique string (UUID recommended)
`Content-Type`	`application/json`

Request body

string

required

Your own stable identifier for this user (e.g. a UUID from your user database). Must be unique within your partner account.

string

User’s email address. Optional; stored for support and notification purposes.

Response

string

Bravado-assigned unique ID for the new user.

string

Echo of the partner_user_id you submitted.

string

The Externally Owned Account address assigned to this user.

string

The Gnosis Safe proxy wallet address where this user’s collateral and positions will be held.

boolean

true if a new user was created (HTTP 201). false if this partner_user_id already existed and the existing account was returned (HTTP 200).

Example

// POST /v2/trade/users
// Idempotency-Key: d0e1f2a3-b4c5-6789-3def-789012345609

{
  "partner_user_id": "user-42",
  "email": "alice@example.com"
}

{
  "bravado_user_id": "bvd_user_789ghi",
  "partner_user_id": "user-42",
  "eoa_address": "0xEOAnew...112233",
  "safe_address": "0xSafeNew...445566",
  "created": true
}

{
  "bravado_user_id": "bvd_user_789ghi",
  "partner_user_id": "user-42",
  "eoa_address": "0xEOAnew...112233",
  "safe_address": "0xSafeNew...445566",
  "created": false
}

Get Started

Supported Prediction Markets

Products Overview

Use Cases

SDKs

Account Snapshot, Balances, and Activity API Reference

GET /v2/trade/account

Response

Example response

GET /v2/trade/balances

Response

Example response

GET /v2/trade/balances/withdrawable

Response

Example response

GET /v2/trade/activity

Query parameters

Response

Example response

POST /v2/trade/users

Request body

Response

Example

​GET /v2/trade/account

​Response

​Example response

​GET /v2/trade/balances

​Response

​Example response

​GET /v2/trade/balances/withdrawable

​Response

​Example response

​GET /v2/trade/activity

​Query parameters

​Response

​Example response

​POST /v2/trade/users

​Request body

​Response

​Example

GET /v2/trade/account

Response

Example response

GET /v2/trade/balances

Response

Example response

GET /v2/trade/balances/withdrawable

Response

Example response

GET /v2/trade/activity

Query parameters

Response

Example response

POST /v2/trade/users

Request body

Response

Example