# coinbase/core-go architecture

> Architecture diagram of the GitHub repository coinbase/core-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coinbase/core-go
- Repository: https://github.com/coinbase/core-go

## Overview

core-go is a small reusable SDK runtime for REST calls, WebSocket connections, and shared value helpers. The main flow is an SDK caller invoking an HTTP verb helper, which serializes the request, applies optional headers, performs the request through the supplied client, then decodes the response or returns a structured error. A separate WebSocket flow dials and wraps a connection before callers can listen for messages. The README documents SDK integration and header/credential support; source excerpts show implementation details for HTTP and WebSockets, but not how consuming SDKs construct credentials.

Main entry points: [`http.go`](https://github.com/coinbase/core-go/blob/main/http.go) (HTTP verbs), [`ws.go`](https://github.com/coinbase/core-go/blob/main/ws.go) (WebSocket dialer), [`ws_model.go`](https://github.com/coinbase/core-go/blob/main/ws_model.go) (WebSocket connection), [`client.go`](https://github.com/coinbase/core-go/blob/main/client.go) (REST client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP requests"]
  node_verbs["HTTP verbs<br/>[http.go]"]
  node_restclient["REST client<br/>[client.go]"]
  node_headers["Header hook<br/>[http.go]"]
  node_response["API response<br/>[http.go]"]
  node_apierror["API errors<br/>[http.go]"]
end

subgraph group_websocket["WebSocket"]
  node_dial["WebSocket dialer<br/>[ws.go]"]
  node_dialconfig["Dial configuration<br/>[ws_model.go]"]
  node_connection["WebSocket connection<br/>[ws_model.go]"]
  node_message_loop["Message listener<br/>[ws.go]"]
  node_ws_helpers["WebSocket helpers<br/>[ws_utils.go]"]
end

subgraph group_shared["Shared utilities"]
  node_values["Value helpers<br/>[utils.go]"]
end

node_sdk(("SDK caller"))
node_transport["HTTP transport"]
node_api["Coinbase API"]
node_ws_service["WebSocket service"]

node_sdk -->|"invokes"| node_verbs
node_verbs -->|"uses client"| node_restclient
node_verbs -->|"applies headers"| node_headers
node_restclient -->|"sends request"| node_transport
node_transport -.->|"HTTP request"| node_api
node_verbs -->|"decodes body"| node_response
node_verbs -->|"returns errors"| node_apierror
node_sdk -->|"configures and dials"| node_dial
node_dial -->|"reads settings"| node_dialconfig
node_dial -.->|"opens socket"| node_ws_service
node_dial -->|"wraps socket"| node_connection
node_sdk -.->|"listens through"| node_message_loop
node_message_loop -->|"reads messages"| node_connection
node_ws_helpers -->|"writes close"| node_connection
node_sdk -.->|"uses helpers"| node_values

click node_verbs "https://github.com/coinbase/core-go/blob/main/http.go"
click node_restclient "https://github.com/coinbase/core-go/blob/main/client.go"
click node_headers "https://github.com/coinbase/core-go/blob/main/http.go"
click node_response "https://github.com/coinbase/core-go/blob/main/http.go"
click node_apierror "https://github.com/coinbase/core-go/blob/main/http.go"
click node_dial "https://github.com/coinbase/core-go/blob/main/ws.go"
click node_dialconfig "https://github.com/coinbase/core-go/blob/main/ws_model.go"
click node_connection "https://github.com/coinbase/core-go/blob/main/ws_model.go"
click node_message_loop "https://github.com/coinbase/core-go/blob/main/ws.go"
click node_ws_helpers "https://github.com/coinbase/core-go/blob/main/ws_utils.go"
click node_values "https://github.com/coinbase/core-go/blob/main/utils.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_verbs,node_restclient,node_headers,node_response,node_apierror toneBlue
class node_dial,node_dialconfig,node_connection,node_message_loop,node_ws_helpers toneAmber
class node_values,node_api toneMint
class node_sdk,node_transport,node_ws_service toneIndigo
```

## Components

### HTTP requests

- [HTTP verbs](https://github.com/coinbase/core-go/blob/main/http.go): `http.go`
- [REST client](https://github.com/coinbase/core-go/blob/main/client.go): `client.go`
- [Header hook](https://github.com/coinbase/core-go/blob/main/http.go): `http.go`
- [API response](https://github.com/coinbase/core-go/blob/main/http.go): `http.go`
- [API errors](https://github.com/coinbase/core-go/blob/main/http.go): `http.go`

### WebSocket

- [WebSocket dialer](https://github.com/coinbase/core-go/blob/main/ws.go): `ws.go`
- [Dial configuration](https://github.com/coinbase/core-go/blob/main/ws_model.go): `ws_model.go`
- [WebSocket connection](https://github.com/coinbase/core-go/blob/main/ws_model.go): `ws_model.go`
- [Message listener](https://github.com/coinbase/core-go/blob/main/ws.go): `ws.go`
- [WebSocket helpers](https://github.com/coinbase/core-go/blob/main/ws_utils.go): `ws_utils.go`

### Shared utilities

- [Value helpers](https://github.com/coinbase/core-go/blob/main/utils.go): `utils.go`

### Other components

- **SDK caller**
- **HTTP transport**
- **Coinbase API**
- **WebSocket service**

## Connections

- SDK caller → HTTP verbs: invokes (evidence: `README.md`)
- HTTP verbs → REST client: uses client (evidence: `http.go`)
- HTTP verbs → Header hook: applies headers (evidence: `http.go`)
- REST client → HTTP transport: sends request
- HTTP transport → Coinbase API: HTTP request
- HTTP verbs → API response: decodes body (evidence: `http.go`)
- HTTP verbs → API errors: returns errors (evidence: `http.go`)
- SDK caller → WebSocket dialer: configures and dials (evidence: `README.md`)
- WebSocket dialer → Dial configuration: reads settings (evidence: `ws.go`)
- WebSocket dialer → WebSocket service: opens socket
- WebSocket dialer → WebSocket connection: wraps socket (evidence: `ws.go`)
- SDK caller → Message listener: listens through
- Message listener → WebSocket connection: reads messages (evidence: `ws.go`)
- WebSocket helpers → WebSocket connection: writes close (evidence: `ws_utils.go`)
- SDK caller → Value helpers: uses helpers
