Coinbase Prime

The Coinbase Prime connector polls a Coinbase Prime portfolio and surfaces its wallets, balances, payments, trading orders, and conversions to the Connectivity service. It is read-only.

Prerequisites#

You need a Coinbase Prime account and an API key with the minimum permissions for the capabilities you use.

To create an API key in the Coinbase Prime console:

Save the API key, API secret, and passphrase — all three are required for the connector configuration.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/coinbaseprime \
  -H "Content-Type: application/json" \
  -d @config.json

With config.json containing:

{
  "apiKey": "string",
  "apiSecret": "string",
  "name": "string",
  "passphrase": "string",
  "pollingPeriod": "30m",
  "portfolioId": "string"
}

Configuration fields#

Capabilities#

• FETCH_ACCOUNTS — portfolio wallets.
• FETCH_BALANCES — per-wallet balances.
• FETCH_PAYMENTS — deposits, withdrawals, internal transfers, rewards, and staking flows.
• FETCH_ORDERS — spot trading orders with full fill lifecycle. Requires Connectivity 3.3.0+.
• FETCH_CONVERSIONS — atomic two-asset swaps (e.g. stablecoin redemption). Requires Connectivity 3.3.0+.

Outbound initiation, webhooks, and external-account creation are not implemented — see Known gaps.

Account model#

Every Connectivity internal account is one Coinbase Prime wallet in the configured portfolio. Coinbase Prime distinguishes wallet types — trading, vault, onchain, custody (QC), and WALLET_TYPE_OTHER — and only trading wallets settle orders. Order resolution is therefore restricted to trading wallets so each asset symbol resolves unambiguously.

The reference is the walletID; defaultAsset is the wallet's symbol (e.g. BTC/8, USD/2). No EXTERNAL accounts are emitted — counterparty addresses surface in Payment metadata only. See Accounts for the cross-connector model.

Payments#

Coinbase Prime transactions land on the Payments stream, excluding rows of type CONVERSION (which feed Conversions). Each upstream transaction lands on exactly one stream.

Transaction type to Payment type#

Status mapping#

Successful transactions → SUCCEEDED; failures and rejections → FAILED; mid-flight → PENDING. Cancellations and expirations map distinctly for dashboarding.

Amount and asset#

Amounts use the precision from Coinbase Prime's asset catalogue (GetAssets provides decimal_precision per symbol). Common assets: BTC/8, ETH/18, USDC/6, USD/2. Always trust the asset field on the Payment rather than assuming a precision.

Transactions referencing an asset not in the catalogue are skipped (logged) and don't produce a Payment.

Account resolution#

Each leg resolves independently:

1. If Coinbase populates transfer_from.value (or transfer_to.value) with type == WALLET, that wallet ID becomes the leg's account reference.
2. Otherwise the connector falls back to the transaction's wallet_id: PAY-IN → destination, PAYOUT → source.
3. External blockchain addresses (e.g. self-custody withdrawal) land in Payment metadata as source_address / deposit_address, never as account references.

Metadata#

Under com.formance.connectors.coinbaseprime.:

• Always present: type, status.
• Present when populated: wallet_id, portfolio_id, network, external_tx_id, source_address, deposit_address, completed_at, blockchain_ids.
• Present when any fee is non-zero: fees, network_fees (only non-zero), fee_symbol.

Example response#

A 1.5 ETH withdrawal from a trading wallet to an external address:

{
  "id": "<formance-payment-id>",
  "connectorID": "<connector-id>",
  "provider": "coinbaseprime",
  "reference": "tx_4f3a8e9d1c",
  "createdAt": "2026-04-30T08:14:22Z",
  "type": "PAYOUT",
  "amount": 1500000000000000000,
  "initialAmount": 1500000000000000000,
  "asset": "ETH/18",
  "scheme": "OTHER",
  "status": "SUCCEEDED",
  "sourceAccountID": "<formance-account-id-of-eth-trading-wallet>",
  "destinationAccountID": null,
  "metadata": {
    "com.formance.connectors.coinbaseprime.type": "WITHDRAWAL",
    "com.formance.connectors.coinbaseprime.status": "TRANSACTION_DONE",
    "com.formance.connectors.coinbaseprime.wallet_id": "wlt_eth_abc123",
    "com.formance.connectors.coinbaseprime.deposit_address": "0xabc1234567890def...",
    "com.formance.connectors.coinbaseprime.fees": "0.0021",
    "com.formance.connectors.coinbaseprime.fee_symbol": "ETH"
  }
}

destinationAccountID is null because the destination is an external blockchain address, preserved in metadata.deposit_address.

Orders#

Coinbase Prime trading orders land on the Orders stream — one record per Coinbase order with an append-only adjustments list capturing each fill or status change.

Direction and account legs#

Both legs are restricted to trading wallets — vault, onchain, and custody are ineligible. If the trading wallet for a symbol hasn't been synced yet, the order page retries on the next cycle (no row is dropped).

Status mapping#

Coinbase Prime statuses map directly to Connectivity statuses, with one exception: PARTIALLY_FILLED is computed locally — Coinbase doesn't expose it. An order becomes PARTIALLY_FILLED when the upstream status is OPEN and the filled quantity sits strictly between zero and the ordered quantity.

Quantities, amounts, and prices#

Metadata#

Under com.formance.connectors.coinbaseprime.:

product_id, portfolio_id, client_order_id, quote_value, filled_value, order_total, exchange_fee, net_average_filled_price, historical_pov, quote_currency, price_asset, base_wallet_id, quote_wallet_id, optional post_only. Commission breakdown adds commission_total, commission_client, commission_venue, commission_ces, commission_financing, commission_regulatory, commission_clearing when Coinbase returns the detail block.

Example response#

A partially-then-fully-filled BUY of 0.5 BTC on BTC-USD at a 50,000 USD limit:

{
  "id": "<formance-order-id>",
  "reference": "ord_9c7e1a4b3d",
  "direction": "BUY",
  "sourceAsset": "USD/2",
  "destinationAsset": "BTC/8",
  "type": "LIMIT",
  "status": "FILLED",
  "timeInForce": "GOOD_UNTIL_CANCELLED",
  "baseQuantityOrdered": 50000000,
  "baseQuantityFilled": 50000000,
  "limitPrice": 5000000,
  "averageFillPrice": 4998750,
  "quoteAmount": 2499375,
  "quoteAsset": "USD/2",
  "priceAsset": "USD/2",
  "fee": 1250,
  "feeAsset": "USD/2",
  "adjustments": [
    { "createdAt": "2026-04-30T09:00:05Z", "status": "PENDING", "baseQuantityFilled": 0 },
    { "createdAt": "2026-04-30T09:00:30Z", "status": "OPEN",    "baseQuantityFilled": 0 },
    { "createdAt": "2026-04-30T09:08:45Z", "status": "PARTIALLY_FILLED", "baseQuantityFilled": 22500000, "fee": 562 },
    { "createdAt": "2026-04-30T09:12:30Z", "status": "FILLED", "baseQuantityFilled": 50000000, "fee": 1250 }
  ]
}

Conversions#

The connector queries Coinbase Prime's transactions feed filtered to type CONVERSION and emits one Conversion per row. Coinbase Prime exposes a single amount field per conversion, so sourceAmount and destinationAmount are populated 1:1 (parsed at each side's precision) — correct for stablecoin redemption (USDC ↔ USD) where nominal value is identical.

Asset and account resolution#

Rows with a missing symbol or one absent from the catalogue are skipped (logged). Account references are used directly without gating on transfer_*.type; either may be empty without blocking emission.

Status mapping#

Conversions have a tighter lifecycle than Payments — no CANCELLED or EXPIRED.

Fees#

fees is parsed at the precision of fee_symbol, falling back to the source symbol when absent. If the fee currency isn't in the catalogue, only the fee is dropped — the conversion itself is still emitted.

Metadata#

Under com.formance.connectors.coinbaseprime.: transaction_id, type (always present); portfolio_id (when populated).

Example response#

A 10,000 USDC → USD conversion (no fee on stablecoin redemption):

{
  "id": "<formance-conversion-id>",
  "reference": "tx_d2b4a17e9c",
  "sourceAsset": "USDC/6",
  "destinationAsset": "USD/2",
  "sourceAmount": 10000000000,
  "destinationAmount": 1000000,
  "fee": null,
  "feeAsset": null,
  "status": "COMPLETED",
  "sourceAccountID": "<formance-account-id-of-usdc-wallet>",
  "destinationAccountID": "<formance-account-id-of-usd-wallet>"
}

Troubleshooting#

Known gaps#

• Outbound initiation — Coinbase Prime exposes withdrawal APIs, but the connector is read-only. CreateTransfer and CreatePayout are not wired.
• Webhooks — not consumed; refresh runs on the polling cycle.
• Historical Orders and Conversions — read from the activity feed forward from the first install cycle; pre-install activity is not back-filled.
• Cross-portfolio aggregation — one connector per portfolioID. Install several to track multiple portfolios.