Use this page to understand how Coinbase Prime transactions appear in the Connectivity API as Payments, and how to list and inspect them once your connector is running.
A Payment represents a single-asset balance movement on a single account leg. Deposits, withdrawals, internal transfers, rewards, and staking events all surface as Payments — conversions are split off onto their own stream.
The Payment model#
Connectivity exposes the following fields on every Payment:
| Field | Description |
|---|---|
id | Formance-assigned unique ID, derived from the connector ID and the upstream reference. |
reference | Coinbase Prime transaction ID. Unique within the connector. |
connectorID, provider | The connector this Payment was fetched from. |
createdAt | When the transaction was created on Coinbase Prime. |
type | One of PAY-IN, PAYOUT, TRANSFER, OTHER. |
status | One of PENDING, SUCCEEDED, FAILED, CANCELLED, EXPIRED, OTHER, UNKNOWN. |
amount, initialAmount | Integer amounts at the asset's precision. |
asset | Asset code with precision suffix (e.g. USD/2, BTC/8). |
scheme | Payment rail. Always OTHER for Coinbase Prime — crypto rails don't fit the card-scheme taxonomy. |
sourceAccountID, destinationAccountID | Resolved Connectivity account IDs (a Coinbase Prime wallet maps to one Connectivity account). Either may be null if the upstream payload didn't carry enough information to resolve it. |
metadata | Coinbase-specific extras under the com.formance.connectors.coinbaseprime. prefix. |
adjustments | History of observed status changes for this Payment. |
Listing and inspecting Payments#
Once the connector is installed and has completed a polling cycle, you can list Payments via the Connectivity API.
curl -s "$STACK/api/payments/v3/payments?pageSize=15" \
-H "Authorization: Bearer $TOKEN" | jqTo filter by connector or status, post a query body:
curl -s "$STACK/api/payments/v3/payments?pageSize=15" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"$match": {"connectorID": "'$CONNECTOR_ID'"}}' | jqYou can also use fctl, which prints a friendlier table — see the Payments concept page for the full fctl payments payments list/get walkthrough.
Mapping from Coinbase Prime#
The connector polls Coinbase Prime's transactions endpoint and emits one Payment per transaction, excluding rows of type CONVERSION. Conversion rows land on the Conversions stream instead, so each upstream transaction lands on exactly one stream.
Transaction type → Payment type#
| Coinbase transaction type | Payment type |
|---|---|
DEPOSIT, COINBASE_DEPOSIT, COINBASE_REFUND, REWARD, DEPOSIT_ADJUSTMENT, CLAIM_REWARDS | PAY-IN |
WITHDRAWAL, SWEEP_WITHDRAWAL, PROXY_WITHDRAWAL, BILLING_WITHDRAWAL, WITHDRAWAL_ADJUSTMENT, SLASH | PAYOUT |
INTERNAL_DEPOSIT, INTERNAL_WITHDRAWAL, SWEEP_DEPOSIT, PROXY_DEPOSIT, STAKE, RESTAKE, PORTFOLIO_STAKE, UNSTAKE, PORTFOLIO_UNSTAKE | TRANSFER |
Chain-level events (KEY_REGISTRATION, DELEGATION, VOTE_AUTHORIZE, ONCHAIN_TRANSACTION, …) and any unrecognised type | OTHER |
Status mapping#
Most successful transactions go straight to SUCCEEDED; failures and rejections become FAILED; everything mid-flight becomes PENDING. Cancellations and expirations are mapped distinctly so you can build dashboards on them.
Amount and asset#
Amounts are parsed at the asset's precision sourced from the Coinbase Prime asset catalogue (the connector calls GetAssets to learn decimal_precision per symbol). For common assets this gives you BTC/8, ETH/18, USDC/6, USD/2, but always trust the actual asset field on the Payment rather than assuming a precision.
If a transaction references an asset that isn't in the catalogue, the connector skips that row and continues with the rest of the page. The skipped row is logged but does not produce a Payment.
Account resolution#
The connector resolves each leg independently:
Use the Coinbase wallet reference if available
For each leg (source and destination), if Coinbase populates transfer_from.value (or transfer_to.value) and the corresponding type is WALLET, that wallet ID becomes the Connectivity account reference for that leg.
Otherwise fall back to the transaction's wallet
If the wallet reference is missing for a leg, the connector falls back to the transaction's wallet_id, applied based on direction:
PAY-IN→ the destination iswallet_idPAYOUT→ the source iswallet_id
External addresses live in metadata only
External blockchain addresses (e.g. on a withdrawal to a self-custody wallet) are surfaced in the Payment's metadata as source_address / deposit_address, never as account references.
Metadata#
Coinbase-specific fields are attached under the com.formance.connectors.coinbaseprime. prefix.
Always present (set even when empty):
type,status
Present when populated:
wallet_id,portfolio_id,network,external_tx_idsource_address,deposit_address(whichever side is set on the transaction)completed_at— RFC3339 timestamp, only when the transaction has settledblockchain_ids— comma-separated, only when the upstream transaction lists them
Present when any fee is non-zero (i.e. when at least one of fees or network_fees is populated):
fees,network_fees— only the non-zero one(s) are writtenfee_symbol— written whenever any fee field is populated
Example response#
A withdrawal of 1.5 ETH from a Coinbase Prime trading wallet to an external address — what the API returns:
{
"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.portfolio_id": "842695ec-67da-4227-a70f-105dbf2bd62a",
"com.formance.connectors.coinbaseprime.network": "ethereum",
"com.formance.connectors.coinbaseprime.deposit_address": "0xabc1234567890def...",
"com.formance.connectors.coinbaseprime.completed_at": "2026-04-30T08:18:55Z",
"com.formance.connectors.coinbaseprime.fees": "0.0021",
"com.formance.connectors.coinbaseprime.fee_symbol": "ETH"
},
"adjustments": [
{ "id": "<adj-1>", "reference": "tx_4f3a8e9d1c", "createdAt": "2026-04-30T08:14:30Z", "status": "PENDING" },
{ "id": "<adj-2>", "reference": "tx_4f3a8e9d1c", "createdAt": "2026-04-30T08:19:00Z", "status": "SUCCEEDED" }
]
}destinationAccountID is null because the destination is an external blockchain address, not a managed Coinbase Prime wallet — the address is preserved in metadata.deposit_address.