@coinbase/cdp-sdk 1.1.2 → 1.3.0

package/analytics.ts

@@ -0,0 +1,142 @@
+import md5 from "md5";
+
+import { CdpClient } from "./client/cdp.js";
+import { EvmClient } from "./client/evm/evm.js";
+import { SolanaClient } from "./client/solana/solana.js";
+
+/**
+ * The data in an error event
+ */
+type ErrorEventData = {
+  /**
+   * The API method where the error occurred, e.g. createAccount, getAccount
+   */
+  method: string;
+  /**
+   * The error message
+   */
+  message: string;
+  /**
+   * The error stack trace
+   */
+  stack?: string;
+  /**
+   * The name of the event. This should match the name in AEC
+   */
+  name: "error";
+};
+
+type EventData = ErrorEventData;
+
+// This is a public client id for the analytics service
+const publicClientId = "54f2ee2fb3d2b901a829940d70fbfc13";
+
+/**
+ * AnalyticsConfig singleton class for holding the API key ID
+ */
+export class AnalyticsConfig {
+  /**
+   * The API key ID
+   */
+  public static apiKeyId: string;
+
+  /**
+   * Sets the API key ID
+   *
+   * @param apiKeyId - The API key ID
+   */
+  public static set(apiKeyId: string): void {
+    AnalyticsConfig.apiKeyId = apiKeyId;
+  }
+}
+
+/**
+ * Sends an analytics event to the default endpoint
+ *
+ * @param event - The event data containing event-specific fields
+ * @returns Promise that resolves when the event is sent
+ */
+export async function sendEvent(event: EventData): Promise<void> {
+  const timestamp = Date.now();
+
+  const enhancedEvent = {
+    user_id: AnalyticsConfig.apiKeyId,
+    event_type: event.name,
+    platform: "server",
+    timestamp,
+    event_properties: {
+      project_name: "cdp-sdk",
+      cdp_sdk_language: "typescript",
+      ...event,
+    },
+  };
+
+  const events = [enhancedEvent];
+  const stringifiedEventData = JSON.stringify(events);
+  const uploadTime = timestamp.toString();
+
+  const checksum = md5(stringifiedEventData + uploadTime);
+
+  const analyticsServiceData = {
+    client: publicClientId,
+    e: stringifiedEventData,
+    checksum,
+  };
+
+  const apiEndpoint = "https://cca-lite.coinbase.com";
+  const eventPath = "/amp";
+  const eventEndPoint = `${apiEndpoint}${eventPath}`;
+
+  await fetch(eventEndPoint, {
+    method: "POST",
+    mode: "no-cors",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(analyticsServiceData),
+  });
+}
+
+/**
+ * Wraps all methods of a class with error tracking.
+ *
+ * @param ClassToWrap - The class whose prototype methods should be wrapped.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function wrapClassWithErrorTracking(ClassToWrap: any): void {
+  const methodNames = Object.getOwnPropertyNames(ClassToWrap.prototype).filter(
+    name => name !== "constructor" && typeof ClassToWrap.prototype[name] === "function",
+  );
+
+  for (const methodName of methodNames) {
+    const originalMethod = ClassToWrap.prototype[methodName];
+    ClassToWrap.prototype[methodName] = async function (...args: unknown[]) {
+      try {
+        return await originalMethod.apply(this, args);
+      } catch (error) {
+        if (!(error instanceof Error)) {
+          return;
+        }
+
+        const { message, stack } = error;
+
+        if (process.env.DISABLE_CDP_ERROR_REPORTING !== "true") {
+          sendEvent({
+            method: String(methodName),
+            message,
+            stack,
+            name: "error",
+          }).catch(() => {
+            // ignore error
+          });
+        }
+
+        throw error;
+      }
+    };
+  }
+}
+
+wrapClassWithErrorTracking(CdpClient);
+wrapClassWithErrorTracking(EvmClient);
+wrapClassWithErrorTracking(SolanaClient);

package/auth/README.md

@@ -0,0 +1,145 @@
+### Overview
+
+The following methods can be used to authenticate your requests to the [Coinbase Developer Platform (CDP)](https://docs.cdp.coinbase.com/). Choose the method that best suits your needs:
+
+| Method | Difficulty | Description |
+| :-- | :-- | :-- |
+| [Use an Axios request client](#use-an-axios-request-interceptor) | Easy | Use an [Axios](https://axios-http.com/docs/intro) client with a pre-configured interceptor that automatically handles authentication for all requests. |
+| [Generate your authorization headers](#generate-your-authorization-headers) | Intermediate | Generate authentication headers and apply them to your preferred HTTP client. |
+| [Generate a JWT](#generate-a-jwt) | Advanced | Generate a JWT token, manually create your authentication headers, and apply them to your preferred HTTP client. |
+
+Visit the [CDP Authentication docs](https://docs.cdp.coinbase.com/api-v2/docs/authentication) for more details.
+
+### Generate a JWT
+
+The following example shows how to generate a JWT token, which can then be injected manually into your `Authorization` header to authenticate REST API requests to the [CDP APIs](https://docs.cdp.coinbase.com/api-v2/docs/welcome) using the HTTP request library of your choice.
+
+**Step 1**: Install the required package:
+
+```bash
+npm install @coinbase/cdp-sdk
+```
+
+**Step 2**: Generate a JWT:
+
+```typescript
+import { generateJwt } from "@coinbase/cdp-sdk/auth";
+
+const jwt = await generateJwt({
+  apiKeyId: "YOUR_API_KEY_ID",
+  apiKeySecret: "YOUR_API_KEY_SECRET",
+  requestMethod: "GET",
+  requestHost: "api.cdp.coinbase.com",
+  requestPath: "/platform/v2/evm/accounts",
+  expiresIn: 120, // optional (defaults to 120 seconds)
+});
+
+console.log(jwt);
+```
+
+For information about the above parameters, please refer to the [Authentication parameters](#authentication-parameters) section.
+
+**Step 3**: Use your JWT (Bearer token) in the `Authorization` header of your HTTP request:
+
+```bash
+curl -L 'https://api.cdp.coinbase.com/platform/v2/evm/accounts' \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Authorization: Bearer $jwt'
+```
+
+### Generate your authorization headers
+
+The following example shows how to generate the required authentication headers for authenticating a request to the [CDP REST APIs](https://docs.cdp.coinbase.com/api-v2/docs/welcome), using the HTTP request library of your choice.
+
+**Step 1**: Install the required package:
+
+```bash
+npm install @coinbase/cdp-sdk
+```
+
+**Step 2**: Generate authorization headers:
+
+```typescript
+import { getAuthHeaders } from "@coinbase/cdp-sdk/auth";
+
+const headers = await getAuthHeaders({
+  apiKeyId: "YOUR_API_KEY_ID",
+  apiKeySecret: "YOUR_API_KEY_SECRET",
+  walletSecret: "YOUR_WALLET_SECRET",
+  requestMethod: "POST",
+  requestHost: "api.cdp.coinbase.com",
+  requestPath: "/platform/v2/evm/accounts",
+  requestBody: {
+    name: "MyAccount",
+  },
+  expiresIn: 120, // optional (defaults to 120 seconds)
+});
+
+console.log(headers);
+```
+
+For information about the above parameters, please refer to the [Authentication parameters](#authentication-parameters) section.
+
+### Use an Axios request interceptor
+
+**Step 1**: Install the required packages:
+
+```bash
+npm install @coinbase/cdp-sdk axios
+```
+
+**Step 2**: Create an authenticated Axios client:
+
+The following example shows how to use an [Axios](https://axios-http.com/docs/intro) HTTP client with a pre-configured interceptor to authenticate your requests to the CDP REST APIs. This client will automatically add the appropriate authentication headers to each request.
+
+```typescript
+import axios from "axios";
+import { axiosHooks } from "@coinbase/cdp-sdk/auth";
+
+// Create an Axios instance
+const axiosClient = axios.create({
+  baseURL: "https://api.cdp.coinbase.com",
+});
+
+// Add authentication to the client
+axiosHooks.withAuth(axiosClient, {
+  apiKeyId: "YOUR_API_KEY_ID",
+  apiKeySecret: "YOUR_API_KEY_SECRET",
+  walletSecret: "YOUR_WALLET_SECRET",
+});
+
+// Make authenticated requests (example)
+// The appropriate authentication headers will be automatically added to the request
+try {
+  const response = await axiosClient.post("/platform/v2/evm/accounts", {
+    name: "MyAccount",
+  });
+  console.log(response.data);
+} catch (error) {
+  console.error("Request failed:", error);
+}
+```
+
+The Axios interceptor will automatically:
+
+- Generate a JWT for each request
+- Add the JWT to the `Authorization` header
+- Set the appropriate `Content-Type` header
+- Add wallet authentication when required
+
+For information about the above parameters, please refer to the [Authentication parameters](#authentication-parameters) section.
+
+### Authentication parameters
+
+The following table provides more context of many of the authentication parameters used in the examples above:
+
+| Parameter | Required | Description |
+| :-- | :-- | :-- |
+| `apiKeyId` | true | The unique identifier for your API key. Supported formats are:<br/>- `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`<br/>- `organizations/{orgId}/apiKeys/{keyId}` |
+| `apiKeySecret` | true | Your API key secret. Supported formats are:<br/>- Edwards key (Ed25519): `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==`<br/>- Elliptic Curve key (ES256): `-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n` |
+| `requestMethod` | true | The HTTP method for the API request you're authenticating (ie, `GET`, `POST`, `PUT`, `DELETE`). |
+| `requestHost` | true | The API host you're calling (ie, `api.cdp.coinbase.com`). |
+| `requestPath` | true | The path of the specific API endpoint you're calling (ie, `/platform/v1/wallets`). |
+| `requestBody` | false | Optional request body data. |
+| `expiresIn` | false | The JWT expiration time in seconds. After this time, the JWT will no longer be valid, and a new one must be generated. Defaults to `120` (ie, 2 minutes) if not specified. |

package/auth/errors.ts

@@ -0,0 +1,59 @@
+/**
+ * A class of errors for capturing stack traces.
+ */
+class BaseError extends Error {
+  /**
+   * Base error constructor.
+   *
+   * @param message - The message to display.
+   */
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * An error for invalid API key format.
+ */
+export class InvalidAPIKeyFormatError extends BaseError {
+  /**
+   * Invalid API key format error constructor.
+   *
+   * @param message - The message to display.
+   */
+  constructor(message: string) {
+    super("Invalid API key format: " + message);
+  }
+}
+
+/**
+ * An error for invalid Wallet Secret format.
+ */
+export class InvalidWalletSecretFormatError extends BaseError {
+  /**
+   * Invalid Wallet Secret format error constructor.
+   *
+   * @param message - The message to display.
+   */
+  constructor(message: string) {
+    super("Invalid Wallet Secret format: " + message);
+  }
+}
+
+/**
+ * An error for an undefined Wallet Secret.
+ */
+export class UndefinedWalletSecretError extends BaseError {
+  /**
+   * Undefined Wallet Secret error constructor.
+   *
+   * @param message - The message to display.
+   */
+  constructor(message: string) {
+    super("Undefined Wallet Secret: " + message);
+  }
+}

package/auth/hooks/axios/index.ts

@@ -0,0 +1 @@
+export * from "./withAuth.js";

package/auth/hooks/axios/withAuth.ts

@@ -0,0 +1,121 @@
+import { AxiosInstance, AxiosHeaders } from "axios";
+
+import { getAuthHeaders } from "../../utils/http.js";
+
+export interface AuthInterceptorOptions {
+  /**
+   * The API key ID
+   *
+   * Examples:
+   *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   */
+  apiKeyId: string;
+
+  /**
+   * The API key secret
+   *
+   * Examples:
+   *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+   *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+   */
+  apiKeySecret: string;
+
+  /** The Wallet Secret */
+  walletSecret?: string;
+
+  /** The source of the request */
+  source?: string;
+
+  /** The version of the source of the request */
+  sourceVersion?: string;
+
+  /** Optional expiration time in seconds (defaults to 120) */
+  expiresIn?: number;
+
+  /** Whether to log request/response details */
+  debug?: boolean;
+}
+
+/**
+ * Axios interceptor for adding the JWT to the Authorization header.
+ *
+ * @param axiosClient - The Axios client instance to add the interceptor to
+ * @param options - Options for the request including API keys and debug flag
+ * @returns The modified request configuration with the Authorization header added
+ */
+export function withAuth(axiosClient: AxiosInstance, options: AuthInterceptorOptions) {
+  axiosClient.interceptors.request.use(async axiosConfig => {
+    const method = axiosConfig.method?.toString().toUpperCase() || "GET";
+
+    if (!axiosConfig.url) {
+      throw new Error("URL is required for authentication");
+    }
+
+    const fullyQualifiedURL = axiosClient.getUri() + axiosConfig.url;
+
+    // Parse URL to get host and path
+    const url = new URL(fullyQualifiedURL);
+
+    // Get authentication headers
+    const headers = await getAuthHeaders({
+      apiKeyId: options.apiKeyId,
+      apiKeySecret: options.apiKeySecret,
+      requestMethod: method,
+      requestHost: url.host,
+      requestPath: url.pathname,
+      requestBody: axiosConfig.data,
+      walletSecret: options.walletSecret,
+      source: options.source,
+      sourceVersion: options.sourceVersion,
+      expiresIn: options.expiresIn,
+    });
+
+    // Add headers to request config
+    axiosConfig.headers = new AxiosHeaders({
+      ...axiosConfig.headers,
+      ...headers,
+    });
+
+    if (options.debug) {
+      console.log("Request:", {
+        method,
+        url: fullyQualifiedURL,
+        headers: axiosConfig.headers,
+        data: axiosConfig.data,
+      });
+    }
+
+    return axiosConfig;
+  });
+
+  if (options.debug) {
+    axiosClient.interceptors.response.use(
+      response => {
+        console.log("Response:", {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+          data: response.data,
+        });
+        return response;
+      },
+      error => {
+        // Ensure we have access to the error response details
+        const errorDetails = {
+          status: error.response?.status,
+          statusText: error.response?.statusText,
+          headers: error.response?.headers,
+          data: error.response?.data,
+          message: error.message,
+          cause: error.cause,
+        };
+
+        console.error("Response Error:", errorDetails);
+        return Promise.reject(error);
+      },
+    );
+  }
+
+  return axiosClient;
+}

package/auth/index.ts

@@ -0,0 +1,5 @@
+import * as axiosHooks from "./hooks/axios/index.js";
+
+export * from "./utils/http.js";
+export * from "./utils/jwt.js";
+export { axiosHooks };

package/auth/utils/http.ts

@@ -0,0 +1,146 @@
+import { generateWalletJwt, generateJwt } from "./jwt.js";
+import { version } from "../../version.js";
+
+/**
+ * Options for generating authentication headers for API requests.
+ */
+export interface GetAuthHeadersOptions {
+  /**
+   * The API key ID
+   *
+   * Examples:
+   *  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   *  'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   */
+  apiKeyId: string;
+
+  /**
+   * The API key secret
+   *
+   * Examples:
+   *  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==' (Edwards key (Ed25519))
+   *  '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n' (EC key (ES256))
+   */
+  apiKeySecret: string;
+
+  /**
+   * The HTTP method for the request (e.g. 'GET', 'POST')
+   */
+  requestMethod: string;
+
+  /**
+   * The host for the request (e.g. 'api.cdp.coinbase.com')
+   */
+  requestHost: string;
+
+  /**
+   * The path for the request (e.g. '/platform/v1/wallets')
+   */
+  requestPath: string;
+
+  /**
+   * Optional request body data
+   */
+  requestBody?: unknown;
+
+  /**
+   * The Wallet Secret for wallet authentication
+   */
+  walletSecret?: string;
+
+  /**
+   * The source identifier for the request
+   */
+  source?: string;
+
+  /**
+   * The version of the source making the request
+   */
+  sourceVersion?: string;
+
+  /**
+   * Optional expiration time in seconds (defaults to 120)
+   */
+  expiresIn?: number;
+}
+
+/**
+ * Gets authentication headers for a request.
+ *
+ * @param options - The configuration options for generating auth headers
+ * @returns Object containing the authentication headers
+ */
+export async function getAuthHeaders(
+  options: GetAuthHeadersOptions,
+): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {};
+
+  // Generate and add JWT token
+  const jwt = await generateJwt({
+    apiKeyId: options.apiKeyId,
+    apiKeySecret: options.apiKeySecret,
+    requestMethod: options.requestMethod,
+    requestHost: options.requestHost,
+    requestPath: options.requestPath,
+    expiresIn: options.expiresIn,
+  });
+  headers["Authorization"] = `Bearer ${jwt}`;
+  headers["Content-Type"] = "application/json";
+
+  // Add wallet auth if needed
+  if (requiresWalletAuth(options.requestMethod, options.requestPath)) {
+    if (!options.walletSecret) {
+      throw new Error(
+        "Wallet Secret not configured. Please set the CDP_WALLET_SECRET environment variable, or pass it as an option to the CdpClient constructor.",
+      );
+    }
+
+    const walletAuthToken = await generateWalletJwt({
+      walletSecret: options.walletSecret,
+      requestMethod: options.requestMethod,
+      requestHost: options.requestHost,
+      requestPath: options.requestPath,
+      requestData: options.requestBody || {},
+    });
+    headers["X-Wallet-Auth"] = walletAuthToken;
+  }
+
+  // Add correlation data
+  headers["Correlation-Context"] = getCorrelationData(options.source, options.sourceVersion);
+
+  return headers;
+}
+
+/**
+ * Returns true if the request indicated by the method and URL requires wallet authentication.
+ *
+ * @param requestMethod - The HTTP method of the request
+ * @param requestPath - The URL path of the request
+ * @returns True if the request requires wallet authentication, false otherwise
+ */
+function requiresWalletAuth(requestMethod: string, requestPath: string): boolean {
+  return (
+    requestPath?.includes("/accounts") && (requestMethod === "POST" || requestMethod === "DELETE")
+  );
+}
+
+/**
+ * Returns encoded correlation data including the SDK version and language.
+ *
+ * @param source - The source identifier for the request
+ * @param sourceVersion - The version of the source making the request
+ * @returns Encoded correlation data as a query string
+ */
+function getCorrelationData(source?: string, sourceVersion?: string): string {
+  const data = {
+    sdk_version: version,
+    sdk_language: "typescript",
+    source: source || "sdk-auth",
+  };
+  if (sourceVersion) {
+    data["source_version"] = sourceVersion;
+  }
+  return Object.keys(data)
+    .map(key => `${key}=${encodeURIComponent(data[key])}`)
+    .join(",");
+}

package/auth/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./http.js";
+export * from "./jwt.js";