Prime Upcoming Changes

This page provides information about upcoming changes to Coinbase Prime Broker.

API Key Enhancements

This change will be published in mid-October 2025 We’re introducing new security and permission features for API keys:

API Key Scopes – Set fine-grained permissions:
- Endpoint-specific access (e.g., allow Get Wallet Balance but not Get Portfolio Balances)
- Category-level READ/WRITE access (e.g., all READ order endpoints only)
- Broad ALL READ / ALL WRITE access across categories

These scopes automatically apply to new endpoints as they are added, requiring no additional setup.

Client Order ID Idempotency

We are introducing Client Order ID (ClOrdID) idempotency across all prime trading surfaces (FIX, REST, & UI). Going forward prime trading will enforce that ClOrdIDs are unique for 24hrs, for both open and closed orders. This change will be scoped at the portfolio level. Consider the following scenario:

Client places a NewOrderSingle (D) with ClOrdID (11) = "test-clordID-1"
The order, "test-clordID-1" fills
Client places another NewOrderSingle (D) with the same clordID (11) "test-clordID-1"
This second order will be rejected with the error message: "duplicate client order ID"

ClOrdID (11) idempotency will continue to be enforced for open orders, scoped at the portfolio level.

Financing API Upgrade

The API will be published in early-October 2025

New Cross Margin Overview API

Financing is rolling out a new API to get the detailed overview for the Cross Margin product. REST Path: GET /v1/entities/<prime_entity_id>/cross_margin Example Response Structure:

{
    "overview": {
        "control_status": "TRADES_AND_WITHDRAWALS",
        "call_status": "ENTITY_NO_CALL",
        "margin_level": "HEALTHY_THRESHOLD",
        "margin_summary": {
            "margin_requirement": "0.00",
            "account_equity": "281.02",
            "margin_excess_shortfall": "281.02",
            "consumed_credit": "10.00",
            "xm_credit_limit": "4000.00",
            "xm_margin_limit": "0.00",
            "spot_equity": "-0.12",
            "futures_equity": "281.15",
            "risk_netting_info": {
                "nodal_margin_requirement": "0.00",
                "portfolio_margin_requirement": "0.00",
                "integrated_portfolio_margin_requirement": "0.00",
                "ineligible_futures_margin_requirement": "0.00",
                "position_margin_requirement": "0.00",
                "portfolio_margin_addon": "0.00",
                "integrated_position_margin_requirement": "0.00",
                "integrated_portfolio_margin_addon": "0.00",
                "netted_futures_notional": "0.00",
                "total_gmv_basis": "0.00",
                "ipm_cash_balance": "-0.12",
                "integrated_scenario_addon": {
                    "amount": "0.00",
                    "add_on_type": "SINGLE_COIN_STRESS"
                },
                "all_integrated_scenario_addons": [
                    {
                        "amount": "0.00",
                        "add_on_type": "SINGLE_COIN_STRESS"
                    },
                    {
                        "amount": "0.00",
                        "add_on_type": "CONCENTRATION_STRESS"
                    },
                    {
                        "amount": "0.00",
                        "add_on_type": "MACRO_STRESS"
                    },
                    {
                        "amount": "0.00",
                        "add_on_type": "SHORT_BIASED_STRESS"
                    }
                ],
                "xm_positions": [
                    {
                        "currency": "USDC",
                        "market_price": "1.00",
                        "margin_eligible": false,
                        "market_cap": "0.00",
                        "adv30_days": "0",
                        "hist5d_vol": "0",
                        "hist30d_vol": "0",
                        "hist90d_vol": "0",
                        "margin_requirement": "0",
                        "spot_balance": "-10.00",
                        "spot_balance_notional": "-10.00",
                        "spot_total_position_margin": "0.00",
                        "futures_balance": "0.00",
                        "futures_balance_notional": "0.00",
                        "futures_total_position_margin": "0.00",
                        "gmv_basis": "0.00",
                        "base_requirement": "0.00",
                        "liq_shorts_add_on": "0.00",
                        "liq_longs_add_on": "0.00",
                        "vol_shorts_add_on": "0",
                        "vol_longs_add_on": "0",
                        "vol5days_add_on": "0",
                        "vol30days_add_on": "0",
                        "vol90days_add_on": "0",
                        "total_position_margin": "0.00"
                    }
                ]
            }
        },
        "active_margin_calls": [
            {
                "margin_call_id": "ce5fbaef-d3da-4818-920c-9e855750b863",
                "currency": "USD",
                "initial_notional_amount": "32083.26",
                "outstanding_notional_amount": "32083.26",
                "margin_call_type": "CALL_TYPE_STANDARD",
                "margin_call_status": "CALL_STATUS_OPEN",
                "called_with_margin_level": "DEFICIT_THRESHOLD",
                "called_with_margin_summary": {
                    "margin_requirement": "0.00",
                    "account_equity": "281.02",
                    "margin_excess_shortfall": "281.02",
                    "consumed_credit": "10.00",
                    "xm_credit_limit": "4000.00",
                    "xm_margin_limit": "0.00",
                    "spot_equity": "-0.12",
                    "futures_equity": "281.15"
                },
                "due_at": "2025-09-25T12:05:02.880848Z",
                "created_at": "2025-09-25T00:05:02.880848Z",
                "updated_at": "2025-09-25T00:05:02.880848Z"
            }
        ],
        "active_loans": [
            {
                "loan_id": "0ceae6a1-7d4f-496a-92bb-6ff085a972c2",
                "loan_party": "CBE",
                "principal_currency": "USDC",
                "principal_currency_market_price": "1",
                "initial_principal_amount": "10",
                "outstanding_principal_amount": "10",
                "created_at": "2025-09-16T16:27:52.284368Z",
                "updated_at": "2025-09-25T00:05:02.880848Z"
            }
        ]
    }
}

Ethereum Pectra Upgrade - Staking API Changes

Update: This will be live in early-October 2025 We are introducing significant enhancements to ETH staking APIs to support the Ethereum Pectra upgrade. These changes enable more flexible staking amounts, introduce a new claim rewards feature, and improve the overall staking experience.

1. Flexible Staking Amounts

Minimum stake amount: 32 ETH (unchanged)
Maximum stake amount per wallet: 180,000 ETH (100 validators × 1,800 ETH target size) by default. You can request for the target validator size to be customized for your Prime Investment vehicle between 32 ETH and 2,048 ETH
NEW: Ability to stake any amount between 32 ETH and 180,000 ETH (not restricted to multiples of 32 ETH)

2. Enhanced Unstaking Capabilities

Minimum unstake amount: 1 ETH (reduced from 32 ETH)
Partial unstaking: Supports flexible amounts (not restricted to multiples of 32 ETH)
Automatic unstaking: Validators with a balance less than 32 ETH will be automatically fully unstaked

3. New Claim Rewards API

After the Pectra upgrade, validator rewards automatically compound and are claimed when you fully unstake. If you want to withdraw rewards without unstaking, you can use this endpoint. REST Path: POST /v1/portfolios/{portfolio_id}/wallets/{wallet_id}/staking/claim_rewards

// Request parameters
{
  "idempotency_key": "string", // Required: Client-generated idempotency key
  "inputs": {
    "amount": "string" // Optional: Amount to claim (ETH only). If omitted, claims maximum available
  }
}

Response:

{
  "wallet_id": "string",
  "transaction_id": "string",
  "activity_id": "string"
}

User generated IDs maximum length requirement

Update: This will be live mid-October 2025 A maximum length requirement of 128 characters will be enforced for client generated IDs. Invalid argument errors will be raised if the IDs are longer than this limit. The affected fields currently are:

Create Portfolio Allocations: allocation_id, allocation_leg_id
Create Portfolio Net Allocations: allocation_leg_id, netting_id
Accept Quote: client_order_id
Create Order: client_order_id
Create Quote Request: client_quote_id

Additional Fields for REST, FIX, and Websocket APIs

Update: This will be live in Q3 Added following fields to Prime Rest API:

Get Order By Order ID and List Portfolio Orders now supports:
- raise_exact which will return a boolean indicating if an order is a raise exact order
- display_base_size and display_quote_size which will return the display size in the order currency. If the order does not have a display size, the response will be empty.
Get Order Preview now supports:
- raise_exact which will return a boolean indicating if an order is a raise exact order
- display_base_size and display_quote_size which will return the display size in the order currency. If the order does not have a display size, the response will be empty.
- stop_price for a Stop Limit order displayed in quote currency
List Order Fills and List Portfolio Fills now supports:
- Add venue_fee which returns the venue fee in quote currency if the entity is enabled for cost-plus pricing.
- Add CES_commission which will return the Client Execution Services commission of the trade.

Important: When using the above endpoints, please note the new parameter validation rules to avoid invalid argument errors:

If user enters both base_quantity and quote_value, an error will be thrown
If user enters base_quantity and display_quote_size, an error will be thrown
If user enters quote_value and display_base_size, an error will be thrown
If user enters both display_quote_size and display_base_size, an error will be thrown

Added following fields to Prime Websocket API:

Orders Channel now supports:
- user_id which will return the unique user_id in each response
- venue_fee which will return the venue fee in quote currency if entity is enabled for cost-plus pricing.
- commission which will return the trading fee of the order.
- CES_commission which will return the Client Execution Services commission of the trade.
Products Channel now supports:
- price_increment
- permissions which always returns PRODUCT_PERMISSION_READ and if the client can trade the product pair will also return PRODUCT_PERMISSION_TRADE

Added following fields to Prime FIX API:

Execution Report (8)
- TimeInForce which will return the Time in force for the order
- StopPrice for a Stop Limit order displayed in quote currency
- MaxShow displays Maximum quantity within an order to be shown to other customers (Display Size). Only present on LIMIT orders.
- FilledValue presents the sum of fills (inclusive of fees) in quote units of an order

FIX Market Data

Update: This will be live in Q3 We will be adding level 2 market data on FIX 5.0 for Prime Trading Spot instruments. This includes OHLCV (Open, High, Low, Close, Volume), bids and offers, and trade history data. This will require a dedicated API key with READ permissions. Logon messages must conform to FIXT 1.1, for example:

Tag	Req	Name	Description
8	Y	BeginString	Must be `FIXT.1.1`
9	Y	BodyLength	Length of body
35	Y	MsgType	Must be `A`
34	Y	MsgSeqNum	Must be `1`
49	Y	SenderCompID	The Service Account ID (on messages from the client)
52	Y	SendingTime	Must be within 5 seconds of server time in UTC
56	Y	TargetCompID	Must be `COIN` (on messages from the client)
95	Y	RawDataLength	Number of bytes in the RawData field
96	Y	RawData	Client message signature (see Logon)
98	Y	EncryptMethod	Must be `0` (none)
108	Y	HeartBtInt	Heartbeat interval is capped at 300s, defaults to 30s
141	Y	ResetSeqNumFlag	Resets the sequence number. Can be `Y`/`N`
553	Y	Username	Client API Key (Replaces tag 9407)
554	Y	Password	Client API passphrase
1137	Y	DefaultApplVerID	Must be `9` (FIX 5.0 SP2)
9406	Y	DropCopyFlag	Must be `N`
10	Y	CheckSum	Checksum

Prime FIX API:

Server will support a new message type sent by the client: MarketDataRequest <V>
Server will send a new message type: MarketDataRequestReject <Y>
Server will send a new message type: MarketDataSnapshotFullRefresh <W>
Server will send a new message type: MarketDataIncrementalRefresh <X>
Server will send a new message type: SecurityStatus <f>

MarketDataRequest (V)

Sent by the client when placing a market data request

Tag	Req	Name	Description
262	Y	MDReqID	Client unique identifier for market data request
263	Y	SubscriptionRequestType	`0` = Snapshot only `1` = Snapshot+Updates (Subscribe) `2` = Disable previous Snapshot+Update (Unsubscribe)
264	Y	MarketDepth	`0` = Full depth (L2) `1` = Top of book `N`>1 = Report best N price tiers of data
265	N	MDUpdateType	Required if SubscriptionRequestType <263> = `1`: `0` = Snapshot+Updates `1` = Updates only
267	Y	NoMDEntryTypes	Number of MDEntryType <269> fields requested
↳269	Y	MDEntryType	`0` = Bid `1` = Offer `2` = Trade `4` = Open `5` = Close `7` = High `8` = Low `B` = Volume
146	Y	NoRelatedSym	Number of Symbols <55> requested
↳55	Y	Symbol	Repeating group of symbols for which the client requests market data

MarketDataRequestReject (Y)

Sent by the server in case the MarketDataRequest (V) fails

Tag	Req	Name	Description
262	Y	MDReqID	Client unique identifier for market data request
281	Y	MDReqRejReason	See MDReqRejReason table
58	N	Text	User friendly error message

MDReqRejReason

Possible values for MDReqRejReason (see MarketDataRequestReject (Y))

Value	Description
0	Unknown symbol
1	Duplicate MDReqID
2	Insufficient bandwidth
3	Insufficient permission
4	Invalid SubscriptionRequestType <263>
5	Invalid MarketDepth <264>
6	Unsupported MDUpdateType <267>
7	Other
8	Unsupported MDEntryType <269>

MarketDataSnapshotFullRefresh (W)

Sent by the server to view a new stream of market data information

Tag	Req	Name	Description
262	Y	MDReqID	Client unique identifier for market data request
55	Y	Symbol	The trading pair from MarketDataRequest
268	Y	NoMDEntries	Number of market data updates in snapshot
911	Y	TotNumReports	Total number of reports being sent in response to a single request
963	Y	ReportID	Unique identifier of the report itself
↳269	Y	MDEntryType	`0` = Bid `1` = Offer `2` = Trade `4` = Open `5` = Close `7` = High `8` = Low `B` = Volume
↳278	Y	MDEntryID	Unique identifier for this market data entry
↳83	Y	RptSeq	Public sequence number for each entry in the snapshot by symbol
↳270	N	MDEntryPx	Price of the market data entry (Not present if MDEntryType = `B`)
↳271	N	MDEntrySize	Volume represented by the market data entry (Not present if MDEntryType = `4`, `5`, `7`, or `8`)
↳272	Y	MDEntryDate	Date of the market data entry
↳2446	N	AggressorSide	If MDEntryType = `2` (Trade), the side of the order: `1` = Buy `2` = Sell
↳273	Y	MDEntryTime	Time of the market data entry
↳453	N	NoPartyIDs	Only present if MdEntryType = `2` (Trade). Will always be `1`
↳↳448	N	PartyID	Market Identifier Code (MIC) for Venue
↳↳447	N	PartyIDSource	Will always be `G`, Market Identifier Code (MIC)
↳↳452	N	PartyRole	Will always be `73`, Execution Venue

MarketDataIncrementalRefresh (X)

Sent by the server to view updates to an existing stream

Tag	Req	Name	Description
262	Y	MDReqID	Client unique identifier for market data request
55	Y	Symbol	The trading pair from MarketDataRequest
268	Y	NoMDEntries	Number of market data updates in snapshot
↳279	Y	MDUpdateAction	Type of entry update: `0` = NEW `1` = CHANGE `2` = DELETE
↳269	Y	MDEntryType	`0` = Bid `1` = Offer `2` = Trade `4` = Open `5` = Close `7` = High `8` = Low `B` = Volume
↳278	Y	MDEntryID	Unique identifier for this market data entry
↳83	Y	RptSeq	Public sequence number for each entry in the snapshot by symbol
↳270	N	MDEntryPx	Price of the market data entry (Not present if MDEntryType = `B`)
↳271	N	MDEntrySize	Volume represented by the market data entry (Not present if MDEntryType = `4`, `5`, `7`, or `8`)
↳272	Y	MDEntryDate	Date of the market data entry
↳2446	N	AggressorSide	If MDEntryType = `2` (Trade), the side of the order: `1`=Buy `2`=Sell
↳273	Y	MDEntryTime	Time of the market data entry
↳453	N	NoPartyIDs	Only present if MdEntryType = `2` (Trade). Will always be `1`
↳↳448	N	PartyID	Market Identifier Code (MIC) for Venue
↳↳447	N	PartyIDSource	Will always be `G`, Market Identifier Code (MIC)
↳↳452	N	PartyRole	Will always be `73`, Execution Venue

SecurityStatus (f)

Sent by the server once when an existing stream fails, and once when it reconnects

Tag	Req	Name	Description
55	Y	Symbol	Symbol
326	Y	SecurityTradingStatus	`3`=Resume `999`=Market data feed temporarily unavailable
58	Y	Text	Market data feed temporarily unavailable for MDReqID `MDReqID` for stream type: `bid/offer` `trade` `OHLCV`

REST Candle Data

Update: This will be live in Q3 We will be adding a new GET endpoint to return candles of specified symbols. The request will require the following parameters: REST Path: GET /v1/portfolios/{portfolio_id}/candles

{
  "product_id": "string",
  "start": "string", // ISO 8601 timestamp e.g 2025-01-10T12:00:00
  "end": "string", // ISO 8601 timestamp e.g 2025-01-10T12:00:00
  "granularity": "string"
}

And will have the following fields in the response body:

{
  "candles": [
    {
      "timestamp": "string", // ISO 8601 timestamp format
      "open": "string",
      "high": "string",
      "low": "string",
      "close": "string",
      "volume": "string"
    }
  ]
}

Settlement Currency

Updating: This will be live in September 2025 We are introducing support for specifying a settlement currency for orders. With this update, clients can access USD trading pairs using USDC positions, enabling them to buy with USDC balances and settle trades directly into USDC positions.

Updated Create Order with new optional parameter settl_currency.

Create Staking/Unstaking Transaction

Updating: This will be live in Late-April We will be adding new POST endpoints to create staking/unstaking transactions. These upcoming endpoints will initially support ETH only. Staking is a request to stake or delegate funds to a validator, and unstaking is a request to unstake delegated or staked funds in a wallet. The request requires the following parameters:

{
  "portfolio_id": "string",
  "wallet_id": "string",
  "body": {
    "idempotency_key": "string", // The idempotency key associated with this transfer
    "inputs": "object" // String map of inputs for the given action.
  }
}

The response will consist of the following:

{
  "wallet_id": "string",
  "transaction_id": "string",
  "activity_id": "string"
}

Get Portfolio Commission

Updating: This will be live in Mid-April We will be adding an optional query parameter to the REST API Get Portfolio Commission endpoint. This parameter will allow you to request commission rates for a specific product ID. The request will look like the following: Path Parameters

{
  "portfolio_id": "string"
}

Query Parameters

{
  "product_id": "string"
}

The response schema remains unchanged.

Prime Multinetwork Support

Updating: This will be live in Mid-March We will be adding a new “network” field that touches the following resources:

Transactions
Wallets
Deposit instructions
Balances

The “network” field will look like the following and will be used as an optional request or response parameter depending on whether the endpoint is a GET or POST:

{
  "id": "string", // The network ID like "ethereum" or "solana"
  "type": "string" // The network type like "mainnet"
}

Additionally, the Get Entity Assets endpoint is updated to return additional information about each network supported by every asset. The response for this endpoint is updated to include `network details”:

{
  "network_details": {
    "network": "object", // The network object as defined above
    "name": "string", // The name of the network like Ethereum or Solana
    "max_decimals": "string", // The maximum number of decimals for the asset on the network
    "default": "boolean", // Whether this is the default network for the asset
    "trading_supported": "boolean", // Whether trading is supported on the network
    "vault_supported": "boolean", // Whether vault is supported on the network
    "prime_custody_supported": "boolean", // Whether prime custody is supported on the network
    "destination_tag_required": "boolean", // Whether destination tag is required on the network
    "network_link": "string" // base url for the recommended block explorer for the network (crypto only)
  }
}

The complete list of endpoints that are updated for this feature can be found under the Changelog.

Update Onchain Address Group

Added: 2025-JAN-18 We will be adding a new endpoint to update a Prime Onchain Wallet address group. This PUT endpoint will replace the existing address group with the new address group. The request requires portfolio ID and address group as shown below:

{
  portfolio_id: string;
  address_group: {
    id;
    name;
    network_type;
    addresses: [{
      name;
      address;
      networks: [string];
    }]
  }
}

The response will consist of the following:

{
  "activity_type": "ACTIVITY_TYPE_ADDRESS_BOOK",
  "num_approvals_remaining": integer,
  "activity_id": string
}

List Onchain Address Groups

Added: 2024-DEC-17 We will be adding a new endpoint to list your onchain address groups. This GET endpoint will list all address groups for a given portfolio ID. The response will consist of the following:

{
  address_groups: [{
    id;
    name;
    network_type;
    added_at;
    addresses: [{
      name;
      address;
      chain_ids: [string]; // This will be empty for solana, * or list of chain IDs for EVM
    }]
  }]
}

Get FCM Risk Limits

Added: 2025-JUN-26 We will be adding a new endpoint to get the risk limits for a given portfolio ID. This GET endpoint will return the risk limits for the specified portfolio. The request requires the following parameters:

{
  "entity_id": "string",
}

The response will consist of the following:

{
  "cfm_risk_limit": "string",
  "cfm_risk_limit_utilization": "string",
  "cfm_total_margin": "string",
  "cfm_delta_ote": "string",
  "cfm_unsettled_realized_pnl": "string",
  "cfm_unsettled_accrued_funding_pnl": "string"
}

Get FCM Margin Call Details

Added: 2025-JUL-02 We will be adding a new endpoint to get the margin call details for a given entity ID. This GET endpoint will return a list of margin calls for the specified entity. The request requires the following parameters:

{
  "entity_id": "string"
}

The response will consist of the following:

{
  "margin_calls": [
    {
      "type": "enum", // "URGENT" or "REGULAR"
      "state": "enum",  // "CLOSED", "ROLLED_OVER", "DEFAULT", "OFFICIAL"
      "initial_amount": "string",
      "remaining_amount": "string",
      "business_date": "string", // UNIX timestamp e.g 1596640920
      "cure_deadline": "string"  // UNIX timestamp e.g 1596650920
    }
  ]
}

GET STARTED

WALLETS

PAYMENTS

TRADING

BASE TOOLS

DATA

AI

STAKING

FAUCET

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

API Key Enhancements

Client Order ID Idempotency

Financing API Upgrade

New Cross Margin Overview API

Ethereum Pectra Upgrade - Staking API Changes

1. Flexible Staking Amounts

2. Enhanced Unstaking Capabilities

3. New Claim Rewards API

User generated IDs maximum length requirement

Additional Fields for REST, FIX, and Websocket APIs

FIX Market Data

MarketDataRequest (V)

MarketDataRequestReject (Y)

MDReqRejReason

MarketDataSnapshotFullRefresh (W)

MarketDataIncrementalRefresh (X)

SecurityStatus (f)

REST Candle Data

Settlement Currency

Create Staking/Unstaking Transaction

Get Portfolio Commission

Prime Multinetwork Support

Update Onchain Address Group

List Onchain Address Groups

Get FCM Risk Limits

Get FCM Margin Call Details

GET STARTED

WALLETS

PAYMENTS

TRADING

BASE TOOLS

DATA

AI

STAKING

FAUCET

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

​API Key Enhancements

​Client Order ID Idempotency

​Financing API Upgrade

​New Cross Margin Overview API

​Ethereum Pectra Upgrade - Staking API Changes

​1. Flexible Staking Amounts

​2. Enhanced Unstaking Capabilities

​3. New Claim Rewards API

​User generated IDs maximum length requirement

​Additional Fields for REST, FIX, and Websocket APIs

​FIX Market Data

​MarketDataRequest (V)

​MarketDataRequestReject (Y)

​MDReqRejReason

​MarketDataSnapshotFullRefresh (W)

​MarketDataIncrementalRefresh (X)

​SecurityStatus (f)

​REST Candle Data

​Settlement Currency

​Create Staking/Unstaking Transaction

​Get Portfolio Commission

​Prime Multinetwork Support

​Update Onchain Address Group

​List Onchain Address Groups

​Get FCM Risk Limits

​Get FCM Margin Call Details

API Key Enhancements

Client Order ID Idempotency

Financing API Upgrade

New Cross Margin Overview API

Ethereum Pectra Upgrade - Staking API Changes

1. Flexible Staking Amounts

2. Enhanced Unstaking Capabilities

3. New Claim Rewards API

User generated IDs maximum length requirement

Additional Fields for REST, FIX, and Websocket APIs

FIX Market Data

MarketDataRequest (V)

MarketDataRequestReject (Y)

MDReqRejReason

MarketDataSnapshotFullRefresh (W)

MarketDataIncrementalRefresh (X)

SecurityStatus (f)

REST Candle Data

Settlement Currency

Create Staking/Unstaking Transaction

Get Portfolio Commission

Prime Multinetwork Support

Update Onchain Address Group

List Onchain Address Groups

Get FCM Risk Limits

Get FCM Margin Call Details