@coinbase/cdp-sdk 1.1.1 → 1.2.0

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,120 @@
+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,
+        };
+
+        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";