The Coinbase Prime connector polls a Coinbase Prime portfolio and surfaces its wallets, balances, payments, trading orders, and conversions to the Connectivity service.
Prerequisites#
Your stack supports Accounts, Balances, and Payments via Coinbase Prime. Orders and Conversions require Connectivity module 3.3.0 or higher (the upcoming release that ships with stack v3.3).
You need a Coinbase Prime account and an API key dedicated to Formance, with the least permissions required for the capabilities you plan to use.
To create an API key in the Coinbase Prime console:
Navigate to API settings
Go to Settings, then API.
Create a new API key
Click Create API Key and select the portfolio you want to connect.
Set expiration
Choose an expiration date as needed.
If you set an expiration date, you will need to update the connector configuration with new credentials when the key expires.
Set permissions
Set Read permissions for the key. As of Payments v3.2, the Coinbase Prime connector is read-only. Configure IP restrictions as needed for your environment.
Save the API key, API secret, and passphrase — you will need all three for the connector configuration.
Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.
Installation#
curl -X POST $FORMANCE_API_URL/api/payments/connectors/coinbaseprime \
-H "Content-Type: application/json" \
-d @config.jsonWith config.json containing:
{
"apiKey": "string",
"apiSecret": "string",
"name": "string",
"passphrase": "string",
"pollingPeriod": "30m",
"portfolioId": "string"
}Configuration fields#
| Field | Required | Default | Description |
|---|---|---|---|
apiKey | yes | — | The API key from Coinbase Prime. |
apiSecret | yes | — | The secret key provided when creating the API key. |
name | yes | — | A unique name for this connector instance. |
passphrase | yes | — | The passphrase provided when creating the API key. |
pollingPeriod | no | 30m | How often the connector polls Coinbase Prime for new data. |
portfolioId | yes | — | The identifier of the portfolio to connect. The connector is scoped to a single portfolio — if you need to track multiple portfolios, create a separate connector instance for each one. |
Capabilities#
The Coinbase Prime connector implements FetchAccounts (portfolio wallets) and FetchBalances (per-wallet balances), plus three streams documented on dedicated pages with the upstream-to-Connectivity field mapping:
How polling works#
A single pollingPeriod drives every capability — Accounts, Balances, Payments, Orders, and Conversions. Each capability holds its own cursor and advances independently.
Orders and Conversions resolve their account legs against the wallets pulled by the Accounts capability, so a freshly-installed connector needs at least one Accounts cycle to complete before Orders and Conversions are usable. If a poll runs before that, the affected page retries on the next cycle — no data is dropped.
Account model#
Every internal account in Connectivity corresponds to a Coinbase Prime wallet within the configured portfolio. Coinbase Prime distinguishes wallet types — trading, vault, onchain, custody (QC), and a generic WALLET_TYPE_OTHER — and only trading wallets settle orders. The connector therefore restricts order resolution to trading wallets, so a single asset symbol always resolves to the correct settlement account.
Two account-reference field names appear in the API depending on the stream:
- Payments expose
sourceAccountID/destinationAccountID, resolved when the upstream payload identifies a wallet, otherwise null. - Orders and Conversions also expose
sourceAccountID/destinationAccountID, always pointing to the resolved Connectivity account ID for the wallet involved.
In all cases, a Coinbase Prime wallet maps one-to-one to a Connectivity account.