Coinbase Integration

The Coinbase integration enables direct connection to Coinbase accounts using the Coinbase API (formerly Coinbase Commerce Developer Platform). This provides real-time access to cryptocurrency holdings, transactions, and balances across all Coinbase wallets.

What Coinbase Connects To

Coinbase integration supports:

Coinbase Wallets: All cryptocurrency wallets in your Coinbase account
Supported Cryptocurrencies: Any crypto supported by Coinbase (Bitcoin, Ethereum, USDC, etc.)
Transaction History: Buys, sells, sends, receives, and conversions
Real-Time Balances: Current holdings and USD values

This integration connects to Coinbase.com accounts only. It does not support Coinbase Pro (now Advanced Trade) or Coinbase Wallet (self-custody) at this time.

Prerequisites

Coinbase Account Required

You need an active Coinbase.com account with verified identity.

Generate API Key

From your Coinbase account:

Log into https://www.coinbase.com
Go to Settings → API
Click “New API Key” or “Create API Key”
Set permissions:
- ✅ Read (required for balance and transaction data)
- ❌ Trade (not needed, keep disabled)
- ❌ Transfer (not needed, keep disabled)
Copy the API Key (starts with organizations/)
Copy the API Secret (save securely, shown only once)

Verify API Version

Ensure you’re using the Coinbase API v3 (CDP API), not the legacy API. The new API uses Ed25519 cryptographic signatures.

Store your API Secret securely. It cannot be retrieved after creation. If lost, you must generate a new API key.

Configuration

Users configure Coinbase credentials directly in the Sure application:

Navigate to Providers

Go to Settings → Providers in your Sure instance.

Add Coinbase Connection

Find the Coinbase section
Click “Add Coinbase Connection”
Enter your API Key
Enter your API Secret
Optionally set a custom name (defaults to “Coinbase”)
Save

Initial Sync

Sure automatically triggers an initial sync to fetch your Coinbase accounts (wallets).

Source: app/controllers/coinbase_items_controller.rb:19

Credential Security

Coinbase API credentials are encrypted using ActiveRecord Encryption:

# Source: app/models/coinbase_item.rb:17
encrypts :api_key, deterministic: true     # For querying
encrypts :api_secret                       # Non-deterministic for max security

Institution Metadata

When you create a Coinbase connection, Sure automatically sets default institution branding:

# Source: app/models/coinbase_item.rb:177
institution_name: "Coinbase"
institution_domain: "coinbase.com"
institution_url: "https://www.coinbase.com"
institution_color: "#0052FF"  # Coinbase brand blue

Connecting Coinbase Accounts

Once credentials are configured, Sure will discover all your Coinbase wallets.

Automatic Account Discovery

After saving credentials:

Sure syncs with Coinbase API
All wallets (BTC, ETH, USDC, etc.) are discovered
You’ll see “Accounts need setup” notification

Setup Accounts

Click “Setup Accounts” or the notification badge
Review the list of discovered wallets
Select which wallets to track in Sure
All Coinbase wallets are automatically created as Crypto accounts
Click “Link Selected Accounts”

Process Holdings

Sure immediately processes holdings so you can see your crypto balances right away.

Source: app/controllers/coinbase_items_controller.rb:229

Account Naming

Coinbase accounts are named after their cryptocurrency:

Bitcoin wallet → “Bitcoin”
Ethereum wallet → “Ethereum”
USD Coin wallet → “USD Coin”

You can rename them in Sure after creation.

Data Syncing

What Gets Synced

Holdings:

Cryptocurrency type and symbol
Quantity owned
Current USD value (or family currency equivalent)
Cost basis (when available)

Transactions:

Buys and sells
Sends and receives
Conversions between cryptos
Fees and commissions
Transaction timestamps and hashes

Balances:

Current balance per wallet
Cash balance (USD in Coinbase)
Total portfolio value

Metadata:

Wallet addresses
Network types
Coinbase branding (logo, colors)

Source: app/models/coinbase_item.rb:42

Sync Frequency

Manual Sync: Click the sync button on your Coinbase connection or any crypto account
Automatic Sync: Can be scheduled (daily, weekly, etc.)
Post-Setup: Immediate sync after linking new accounts

Coinbase does not provide webhooks for balance changes, so all syncs are initiated by Sure. Source: app/controllers/coinbase_items_controller.rb:94

Cryptocurrency prices fluctuate constantly. Sync frequently for accurate portfolio values, or rely on Sure’s valuation system which uses latest market prices.

Processing Holdings

Coinbase holdings are processed immediately during account setup:

# Source: app/controllers/coinbase_items_controller.rb:268
begin
  CoinbaseAccount::HoldingsProcessor.new(coinbase_account).process
rescue => e
  Rails.logger.error("Failed to process holdings: #{e.message}")
end

This ensures you see your crypto balances as soon as accounts are linked.

Managing Coinbase Connections

Updating Credentials

If you rotate your API keys:

Generate New Key

Create a new API key in Coinbase Settings → API

Update in Sure

Go to Settings → Providers
Find your Coinbase connection
Click “Edit”
Enter the new API Key and API Secret
Save

Verify

Trigger a manual sync to ensure the new credentials work.

Source: app/controllers/coinbase_items_controller.rb:58

Linking to Existing Accounts

If you’ve already created manual crypto accounts in Sure:

From Account Page

Navigate to the manual crypto account
Click “Link to Provider”
Select “Coinbase”

Choose Coinbase Wallet

Select the matching Coinbase wallet from the list
Confirm linking

Sync

Sure will sync holdings to the linked account.

Source: app/controllers/coinbase_items_controller.rb:137

Removing Connection

To disconnect Coinbase:

Go to Settings → Providers
Find the Coinbase connection
Click “Delete”
Confirm deletion

This will:

Schedule the connection for deletion
Unlink all associated crypto accounts
Preserve transaction history in Sure
Not affect your Coinbase account or API key

Source: app/controllers/coinbase_items_controller.rb:89

Troubleshooting

”Invalid API Key” or “Authentication Failed”

Causes:

API key was copied incorrectly
API secret was copied incorrectly
API key was deleted or revoked in Coinbase
Using old Coinbase API v2 credentials instead of v3

Solution:

Verify you’re using Coinbase API v3 (CDP API)
Generate a fresh API key in Coinbase
Ensure the key has Read permission
Copy and paste carefully (no extra spaces)
Update credentials in Sure

”No Accounts Found”

Cause: Your Coinbase account has no wallets with balances. Solution:

Transfer some crypto into your Coinbase account
Ensure wallets are visible in Coinbase.com
Try a manual sync after adding funds

”Decryption Error”

Cause: ActiveRecord Encryption keys changed or are missing. Solution: Ensure these environment variables are set:

ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=...
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=...
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=...

If keys were lost, you’ll need to delete and recreate the Coinbase connection.

Holdings Not Updating

Checklist:

Verify API key still has Read permission
Check if Coinbase API is operational
Trigger a manual sync
Review logs for API errors
Ensure accounts are linked (not just connected)

Source: app/models/coinbase_item.rb:55

USD Values Incorrect

Cause: Cryptocurrency prices change rapidly. Solution:

Sync more frequently for accurate values
Sure uses latest market prices from its valuation system
Check if the crypto’s market data source is available

API Reference

Creating a Coinbase Connection

# Source: app/controllers/coinbase_items_controller.rb:19
@coinbase_item = Current.family.coinbase_items.build(
  name: "My Coinbase",
  api_key: "organizations/...",
  api_secret: "..."
)
@coinbase_item.save
@coinbase_item.set_coinbase_institution_defaults!
@coinbase_item.sync_later

Importing Data

# Source: app/models/coinbase_item.rb:42
def import_latest_coinbase_data
  provider = coinbase_provider
  CoinbaseItem::Importer.new(
    self, 
    coinbase_provider: provider
  ).import
end

Processing Holdings

# Source: app/models/coinbase_item.rb:55
def process_accounts
  linked = coinbase_accounts.joins(:account).merge(Account.visible)
  
  linked.each do |coinbase_account|
    CoinbaseAccount::Processor.new(coinbase_account).process
  end
end

Technical Implementation

Authentication

Coinbase CDP API uses Ed25519 cryptographic signatures:

# Gemfile includes:
gem "ed25519"  # For Coinbase CDP API authentication

Source: Gemfile:56

Account Type

All Coinbase accounts are created as Crypto accountable type:

# Source: app/controllers/coinbase_items_controller.rb:259
account = Account.create_from_coinbase_account(coinbase_account)
# Always creates accountable_type: "Crypto"

Best Practices

Read-Only Keys: Only grant Read permission when creating API keys
Rotate Keys: Periodically rotate API keys for security
Sync Frequency: Sync at least daily for accurate portfolio tracking
Account Setup: Guide users through account setup after initial connection
Holdings Processing: Process holdings immediately for better UX
Error Handling: Log API errors and prompt users to check credentials
Security: Never expose API secrets in logs or UI

Limitations

Coinbase Only: Does not support Coinbase Pro/Advanced Trade or Coinbase Wallet
No Webhooks: Must rely on manual/scheduled syncs for updates
API Rate Limits: Coinbase may rate-limit frequent API calls
No Staking Info: Staking rewards may not be fully detailed
No NFTs: NFT holdings are not currently synced

Comparison: Coinbase vs Manual Entry

Feature	Coinbase API	Manual Entry
Setup	API key required	No prerequisites
Syncing	Automatic	Manual
Holdings	✅ Real-time	⚠️ Manual updates
Transactions	✅ Complete history	⚠️ Manual entry
Accuracy	✅ Always accurate	⚠️ Depends on user
Privacy	⚠️ API access	✅ No external connection
Cost	Free (API usage)	Free

Additional Resources

Coinbase API Documentation

Official Coinbase Developer Platform docs

Coinbase API Keys

Manage your API keys in Coinbase

SnapTrade for Crypto

Alternative for crypto exchange accounts

Get Started

Self-Hosting

Core Features

Integrations

Mobile App

​What Coinbase Connects To

​Prerequisites

​Configuration

​Credential Security

​Institution Metadata

​Connecting Coinbase Accounts

​Account Naming

​Data Syncing

​What Gets Synced

​Sync Frequency

​Processing Holdings

​Managing Coinbase Connections

​Updating Credentials

​Linking to Existing Accounts

​Removing Connection

​Troubleshooting

​”Invalid API Key” or “Authentication Failed”

​”No Accounts Found”

​”Decryption Error”

​Holdings Not Updating

​USD Values Incorrect

​API Reference

​Creating a Coinbase Connection

​Importing Data

​Processing Holdings

​Technical Implementation

​Authentication

​Account Type

​Best Practices

​Limitations

​Comparison: Coinbase vs Manual Entry

​Additional Resources

Coinbase API Documentation

Coinbase API Keys

SnapTrade for Crypto

Build docs developers (and LLMs) love

What Coinbase Connects To

Prerequisites

Configuration

Credential Security

Institution Metadata

Connecting Coinbase Accounts

Account Naming

Data Syncing

What Gets Synced

Sync Frequency

Processing Holdings

Managing Coinbase Connections

Updating Credentials

Linking to Existing Accounts

Removing Connection

Troubleshooting

”Invalid API Key” or “Authentication Failed”

”No Accounts Found”

”Decryption Error”

Holdings Not Updating

USD Values Incorrect

API Reference

Creating a Coinbase Connection

Importing Data

Processing Holdings

Technical Implementation

Authentication

Account Type

Best Practices

Limitations

Comparison: Coinbase vs Manual Entry

Additional Resources