feat(generator): build full SDK generation foundation

.github/workflows/test.yml

@@ -29,3 +29,34 @@ jobs:
 
       - name: Javadoc
         run: mvn -B javadoc:javadoc
+
+      - name: Generator tests
+        run: mvn -B -f tools/model-generator/pom.xml test
+
+  generated-sdk:
+    # Regenerates the SDK from the committed spec inside the disposable CI checkout and proves the
+    # result compiles and passes the SDK tests. Generated output is not committed in this phase;
+    # once a baseline is committed, `make check-generated` replaces this job as the gate.
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Java
+        uses: actions/setup-java@f2beeb24e141e01a676f977032f5a29d81c9e27e # v5.1.0
+        with:
+          distribution: temurin
+          java-version: "11"
+          cache: maven
+
+      - name: Generate SDK from committed spec
+        run: make generate
+
+      - name: Test generated SDK
+        run: mvn -B test

.gitignore

@@ -22,6 +22,7 @@ dependency-reduced-pom.xml
 tmp/
 
 ai-docs/
+docs/
 
 # SDK generator download + OpenAPI CLI output
 generated/

Makefile

@@ -1,10 +1,20 @@
-.PHONY: fetch-spec compile format
+.PHONY: fetch-spec compile format generate check-generated generate-live-diff
+
 fetch-spec:
-	@mkdir -p apiSpec
-	@curl -fsSL -o apiSpec/prime-public-spec.yaml https://api.prime.coinbase.com/v1/openapi.yaml
+	mvn -B -f tools/model-generator/pom.xml compile exec:java@generate-models -Dexec.args="--fetch-spec"
 
 compile:
 	mvn -B compile
 
 format:
 	mvn -B spotless:apply
+
+generate:
+	mvn -B -f tools/model-generator/pom.xml compile exec:java@generate-models
+	mvn -B spotless:apply
+
+check-generated:
+	mvn -B -f tools/model-generator/pom.xml compile exec:java@generate-models -Dexec.args="--check"
+
+generate-live-diff:
+	mvn -B -f tools/model-generator/pom.xml compile exec:java@generate-models -Dexec.args="--live-diff"

src/main/java/com/coinbase/prime/client/CoinbasePrimeClient.java

@@ -29,34 +29,52 @@
 import java.util.List;
 
 public class CoinbasePrimeClient extends CoinbaseNetHttpClient {
+  private final String baseUrl;
+  private final HttpClient httpClient;
+
   public CoinbasePrimeClient(CoinbasePrimeCredentials credentials, String baseUrl) {
     super(credentials, baseUrl);
+    this.baseUrl = baseUrl;
+    this.httpClient = null;
   }
 
   public CoinbasePrimeClient(
       CoinbasePrimeCredentials credentials, String baseUrl, HttpClient client) {
     super(credentials, baseUrl, client);
+    this.baseUrl = baseUrl;
+    this.httpClient = client;
   }
 
   public CoinbasePrimeClient(CoinbasePrimeCredentials credentials) {
     super(credentials, Constants.CB_PRIME_BASE_URL);
+    this.baseUrl = Constants.CB_PRIME_BASE_URL;
+    this.httpClient = null;
   }
 
   public CoinbasePrimeClient(CoinbasePrimeCredentials credentials, HttpClient client) {
     super(credentials, Constants.CB_PRIME_BASE_URL, client);
+    this.baseUrl = Constants.CB_PRIME_BASE_URL;
+    this.httpClient = client;
+  }
+
+  public String getBaseUrl() {
+    return baseUrl;
   }
 
   /**
-   * Returns a new client with the given base URL; credentials and behavior are otherwise unchanged.
-   * Prefer this for single-call version overrides (e.g. {@code v2}) without mutating the shared
-   * client.
+   * Returns a new client with the given base URL; credentials and the injected HttpClient are
+   * reused. Prefer this for single-call version overrides (e.g. {@code v2}) without mutating the
+   * shared client.
    */
   public CoinbasePrimeClient withBaseUrl(String baseUrl) {
     CoinbaseCredentials credentials = getCredentials();
     if (!(credentials instanceof CoinbasePrimeCredentials)) {
       throw new IllegalStateException("Credentials must be CoinbasePrimeCredentials");
     }
-    return new CoinbasePrimeClient((CoinbasePrimeCredentials) credentials, baseUrl);
+    CoinbasePrimeCredentials primeCredentials = (CoinbasePrimeCredentials) credentials;
+    return httpClient == null
+        ? new CoinbasePrimeClient(primeCredentials, baseUrl)
+        : new CoinbasePrimeClient(primeCredentials, baseUrl, httpClient);
   }
 
   @Override

src/test/java/com/coinbase/prime/client/CoinbasePrimeClientTest.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2026-present Coinbase Global, Inc.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.coinbase.prime.client;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+import com.coinbase.core.client.CoinbaseNetHttpClient;
+import com.coinbase.prime.credentials.CoinbasePrimeCredentials;
+import java.lang.reflect.Field;
+import java.net.http.HttpClient;
+import org.junit.jupiter.api.Test;
+
+class CoinbasePrimeClientTest {
+  private static final CoinbasePrimeCredentials CREDENTIALS =
+      new CoinbasePrimeCredentials("test-access-key", "test-passphrase", "test-signing-key");
+
+  @Test
+  void withBaseUrlReusesInjectedHttpClient() throws Exception {
+    HttpClient injected = HttpClient.newHttpClient();
+    CoinbasePrimeClient client =
+        new CoinbasePrimeClient(CREDENTIALS, "https://example.test/v1", injected);
+
+    CoinbasePrimeClient v2 = client.withBaseUrl("https://example.test/v2");
+
+    assertEquals("https://example.test/v2", v2.getBaseUrl());
+    assertSame(injected, transport(v2));
+  }
+
+  @Test
+  void withBaseUrlKeepsDefaultTransportWhenNoneInjected() {
+    CoinbasePrimeClient v2 =
+        new CoinbasePrimeClient(CREDENTIALS).withBaseUrl("https://example.test/v2");
+
+    assertEquals("https://example.test/v2", v2.getBaseUrl());
+  }
+
+  private static HttpClient transport(CoinbasePrimeClient client) throws Exception {
+    Field field = CoinbaseNetHttpClient.class.getDeclaredField("client");
+    field.setAccessible(true);
+    return (HttpClient) field.get(client);
+  }
+}

tools/model-generator/.openapi-generator-ignore

@@ -6,12 +6,9 @@
 src/main/java/com/coinbase/prime/model/*Request.java
 src/main/java/com/coinbase/prime/model/*Response.java
 
-# Per-operation typed error payloads and codes (not consumed by the SDK yet)
+# Per-operation typed error payloads are not consumed by the SDK yet. ErrorCode and
+# Subcode enums are intentionally generated and routed to model/errors by PostProcessor.
 src/main/java/com/coinbase/prime/model/*ErrorResponse.java
-src/main/java/com/coinbase/prime/model/*ErrorCode.java
-src/main/java/com/coinbase/prime/model/*Subcode.java
-src/main/java/com/coinbase/prime/model/enums/*ErrorCode.java
-src/main/java/com/coinbase/prime/model/enums/*Subcode.java
 
 # Google infrastructure types (google.type.Date is generated as GoogleTypeDate and renamed to DateOfBirth)
 src/main/java/com/coinbase/prime/model/GoogleProtobufAny.java

tools/model-generator/config/generator-config.json

@@ -0,0 +1,26 @@
+{
+  "specUrl": "https://api.prime.coinbase.com/v1/openapi.yaml",
+  "committedSpecPath": "apiSpec/prime-public-spec.yaml",
+  "tagToFolderOverrides": {
+    "Travel Rule": "transactions"
+  },
+  "modelTypeMappings": {
+    "CreateOnchainTransactionRequestEVMParams": "EvmParams",
+    "CreateOnchainTransactionRequestEvmParams": "EvmParams",
+    "FcmFuturesSweepRequestAmount": "SweepAmount",
+    "FcmFuturesSweep": "FuturesSweep",
+    "EvmParam": "EvmParams",
+    "RPC": "RpcConfig",
+    "XMControlStatus": "PrimeXMControlStatus",
+    "XMMarginLevel": "PrimeXMMarginLevel"
+  },
+  "sharedModelMappings": {
+    "PaginatedResponse": "com.coinbase.prime.common.Pagination"
+  },
+  "protectedCompatibilityFiles": [
+    "com/coinbase/prime/portfolios/GetPortfolioCounterpartyIdRequest.java",
+    "com/coinbase/prime/portfolios/GetPortfolioCounterpartyIdResponse.java",
+    "com/coinbase/prime/portfolios/PortfoliosService.java",
+    "com/coinbase/prime/portfolios/PortfoliosServiceImpl.java"
+  ]
+}

tools/model-generator/config/naming-parity.json

@@ -0,0 +1,100 @@
+[
+  {
+    "operationId": "PrimeRESTAPI_CreateWalletTransfer",
+    "canonicalJavaMethod": "createTransfer",
+    "legacyJavaAliases": ["createWalletTransfer"],
+    "serviceFolder": "transactions",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_CreateWalletWithdrawal",
+    "canonicalJavaMethod": "createWithdrawal",
+    "legacyJavaAliases": ["createWalletWithdrawal"],
+    "serviceFolder": "transactions",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetOrder",
+    "canonicalJavaMethod": "getOrder",
+    "legacyJavaAliases": ["getOrderByOrderId"],
+    "serviceFolder": "orders",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_StakingClaimRewards",
+    "canonicalJavaMethod": "claimStakingRewards",
+    "legacyJavaAliases": ["claimRewards"],
+    "serviceFolder": "staking",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_PortfolioStakingInitiate",
+    "canonicalJavaMethod": "createPortfolioStake",
+    "legacyJavaAliases": ["portfolioStakingInitiate"],
+    "serviceFolder": "staking",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_PortfolioStakingUnstake",
+    "canonicalJavaMethod": "createPortfolioUnstake",
+    "legacyJavaAliases": ["portfolioStakingUnstake"],
+    "serviceFolder": "staking",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetEntityPaymentMethods",
+    "canonicalJavaMethod": "listEntityPaymentMethods",
+    "legacyJavaAliases": ["listPaymentMethods"],
+    "serviceFolder": "paymentmethods",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetEntityPaymentMethodDetails",
+    "canonicalJavaMethod": "getEntityPaymentMethod",
+    "legacyJavaAliases": ["getPaymentMethodDetails"],
+    "serviceFolder": "paymentmethods",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetPortfolioActivities",
+    "canonicalJavaMethod": "listActivities",
+    "legacyJavaAliases": ["listPortfolioActivities"],
+    "serviceFolder": "activities",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetPortfolioAddressBook",
+    "canonicalJavaMethod": "getAddressBook",
+    "legacyJavaAliases": ["listAddressBook"],
+    "serviceFolder": "addressbook",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetAllocationsByClientNettingId",
+    "canonicalJavaMethod": "getAllocationsByClientNettingId",
+    "legacyJavaAliases": ["listAllocationsByNettingId"],
+    "serviceFolder": "allocations",
+    "aliasBehavior": "requestResponseSubclass"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetEntityUsers",
+    "canonicalJavaMethod": "listEntityUsers",
+    "legacyJavaAliases": [],
+    "serviceFolder": "users",
+    "aliasBehavior": "none"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetFcmBalance",
+    "canonicalJavaMethod": "getEntityFcmBalance",
+    "legacyJavaAliases": [],
+    "serviceFolder": "futures",
+    "aliasBehavior": "none"
+  },
+  {
+    "operationId": "PrimeRESTAPI_GetPortfolioCounterpartyID",
+    "canonicalJavaMethod": "getPortfolioCounterpartyId",
+    "legacyJavaAliases": [],
+    "serviceFolder": "advancedtransfer",
+    "aliasBehavior": "none"
+  }
+]