@coinbase/cdp-sdk
Version:
SDK for interacting with the Coinbase Developer Platform Wallet API
535 lines (516 loc) • 22.4 kB
text/typescript
/**
* @module DepositDestinations
*/
// This file was auto-generated by Fern from our API Definition.
import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../BaseClient.js";
import { mergeHeaders, mergeOnlyDefinedHeaders } from "../../../../core/headers.js";
import * as core from "../../../../core/index.js";
import * as environments from "../../../../environments.js";
import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
import * as errors from "../../../../errors/index.js";
import * as CoinbaseApi from "../../../index.js";
export declare namespace DepositDestinationsClient {
export type Options = BaseClientOptions;
export interface RequestOptions extends BaseRequestOptions {}
}
/**
* Deposit Destinations allow you to manage where funds can be deposited into your accounts.
*
* ## Crypto Deposit Destinations
*
* Crypto deposit destinations are cryptocurrency addresses that you can generate and fetch via the API. Once created, these addresses can receive cryptocurrency payments on their specified network. By default, incoming funds are credited to your account balance (`target.accountId`); you can instead route funds directly to an external onchain address by setting `target` to an onchain address (`target.address`, `target.network`, `target.asset`, and optionally `target.destinationTag`).
*
* **Metadata:**
* You can attach metadata to any deposit destination you create to track the purpose or source of deposits.
*
*
* **Example (target: account balance):**
* ```json
* {
* "depositDestinationId": "depositDestination_123",
* "accountId": "account_456",
* "type": "crypto",
* "crypto": {
* "network": "base",
* "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
* },
* "target": {
* "accountId": "account_789",
* "asset": "usd"
* },
* "status": "active",
* "metadata": {
* "customer_id": "cust_789",
* "reference": "order-12345"
* }
* }
* ```
* **Example (target: onchain address):**
* ```json
* {
* "depositDestinationId": "depositDestination_123",
* "accountId": "account_456",
* "type": "crypto",
* "crypto": {
* "network": "base",
* "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
* },
* "target": {
* "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
* "network": "base",
* "asset": "usdc"
* },
* "status": "active",
* "metadata": {
* "customer_id": "cust_789",
* "reference": "order-12345"
* }
* }
* ```
* Use the list endpoint to retrieve all deposit destinations.
*
* ## Fiat Deposit Destinations
*
* <Warning>
* Fiat deposit destinations are currently in **private beta** and require account enablement. Contact your Coinbase representative for access. Fields and behavior may change before general availability.
* </Warning>
*
* Fiat deposit destinations are bank accounts provisioned on your behalf that let an account receive USD deposits over a supported payment rail (for example, ACH). Each fiat deposit destination represents a single bank account at a single banking partner and is keyed by `accountType` (for example, `us_bank`).
*
* **Example:**
* ```json
* {
* "depositDestinationId": "depositDestination_cf4958d2-b068-6bf9-da01-eee44f157336",
* "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* "type": "fiat",
* "status": "pending",
* "fiat": {
* "accountType": "us_bank",
* "currency": "usd",
* "bankName": "Citibank N.A.",
* "beneficiaryName": "John Smith",
* "routingNumber": "987654321",
* "accountNumber": "123456789",
* "bankAddress": "399 Park Avenue, New York, NY 10022",
* "supportedRails": ["ach", "fedwire"]
* },
* "target": {
* "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* "asset": "usdc"
* }
* }
* ```
* Use the create endpoint to provision a fiat deposit destination for an account.
*/
export class DepositDestinationsClient {
protected readonly _options: NormalizedClientOptionsWithAuth<DepositDestinationsClient.Options>;
constructor(options: DepositDestinationsClient.Options) {
this._options = normalizeClientOptionsWithAuth(options);
}
/**
* List deposit destinations. You can optionally filter the results by type, account ID, network, cryptocurrency address, or status. Results are sorted by creation date in descending order (newest first).
*
* @param {CoinbaseApi.ListDepositDestinationsRequest} request
* @param {DepositDestinationsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws CoinbaseApi.BadRequestError
* @throws CoinbaseApi.UnauthorizedError
* @throws CoinbaseApi.InternalServerError
*
* @example
* ```ts
* await client.depositDestinations.listDepositDestinations({
* accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
* type: "crypto",
* network: "base",
* pageToken: "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
* })
* ```
*/
public listDepositDestinations(
request: CoinbaseApi.ListDepositDestinationsRequest = {},
requestOptions?: DepositDestinationsClient.RequestOptions,
): core.HttpResponsePromise<CoinbaseApi.ListDepositDestinationsResponse> {
return core.HttpResponsePromise.fromPromise(this.__listDepositDestinations(request, requestOptions));
}
private async __listDepositDestinations(
request: CoinbaseApi.ListDepositDestinationsRequest = {},
requestOptions?: DepositDestinationsClient.RequestOptions,
): Promise<core.WithRawResponse<CoinbaseApi.ListDepositDestinationsResponse>> {
const _metadata: core.EndpointMetadata = {
security: [{ apiKeyAuth: [] }],
method: "GET",
path: "v2/deposit-destinations",
operationId: "endpoint_depositDestinations.listDepositDestinations",
};
const { accountId, address, type: type_, network, status, pageSize, pageToken } = request;
const _queryParams: Record<string, unknown> = {
accountId,
address,
type: type_,
network,
status: status != null ? status : undefined,
pageSize,
pageToken,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest({
endpointMetadata: _metadata,
clientOptions: this._options,
request: {
method: "GET",
},
});
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
requestOptions?.headers,
);
const _response = await core.fetcher({
url: core.url.join(
(await core.Supplier.get(this._options.baseUrl)) ??
(await core.Supplier.get(this._options.environment)) ??
environments.CoinbaseApiEnvironment.Default,
"v2/deposit-destinations",
),
method: "GET",
headers: _headers,
queryString: core.url
.queryBuilder()
.addMany(_queryParams)
.mergeAdditional(requestOptions?.queryParams)
.build(),
timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
abortSignal: requestOptions?.abortSignal,
endpointMetadata: _metadata,
fetchFn: this._options?.fetch,
logging: this._options.logging,
});
if (_response.ok) {
return {
data: _response.body as CoinbaseApi.ListDepositDestinationsResponse,
rawResponse: _response.rawResponse,
};
}
if (_response.error.reason === "status-code") {
switch (_response.error.statusCode) {
case 400:
throw new CoinbaseApi.BadRequestError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 401:
throw new CoinbaseApi.UnauthorizedError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 500:
throw new CoinbaseApi.InternalServerError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
default:
throw new errors.CoinbaseApiError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v2/deposit-destinations");
}
/**
* Create a new deposit destination for an account. Two types are supported:
*
* - `crypto` (public): provisions a cryptocurrency address on the requested
* network. The returned `crypto.address` is the deposit address; funds
* sent to it are credited to the `target` account in the specified asset.
* For Customer-owned accounts, the Customer must have the `custodyCrypto`
* and `custodyStablecoin` capabilities enabled.
*
*
* - `fiat` (private-beta): provisions a bank
* account at a CDP banking partner. The server picks the account type
* (e.g. `us_bank`) and supported payment rails based on the account's
* eligibility; pass `fiat.paymentRail` to influence partner selection.
* The returned `fiat` object contains the bank account details the
* depositor needs to send funds. For Customer-owned accounts, the Customer
* must have the `custodyFiat` capability enabled. Requires account
* enablement — contact your Coinbase representative for access. Fields
* and behavior may change before general availability.
*
*
* For Customer-owned accounts not authorized for the required capabilities,
* the request is rejected with `customer_not_authorized` (HTTP 403).
*
*
* The created destination's `status` starts as `pending` for fiat (it
* becomes `active` once the partner provisioning callback completes) and
* `active` for crypto.
*
* @param {CoinbaseApi.CreateDepositDestinationBody} request
* @param {DepositDestinationsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws CoinbaseApi.BadRequestError
* @throws CoinbaseApi.UnauthorizedError
* @throws CoinbaseApi.ForbiddenError
* @throws CoinbaseApi.NotFoundError
* @throws CoinbaseApi.ConflictError
* @throws CoinbaseApi.UnprocessableEntityError
* @throws CoinbaseApi.InternalServerError
* @throws CoinbaseApi.ServiceUnavailableError
*
* @example
* ```ts
* await client.depositDestinations.createDepositDestination({
* idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324",
* type: "crypto",
* accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* target: {
* accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* asset: "usd"
* },
* metadata: {
* "customer_id": "123e4567-e89b-12d3-a456-426614174000",
* "reference": "order-12345"
* },
* crypto: {
* network: "base"
* }
* })
* ```
*
* @example
* ```ts
* await client.depositDestinations.createDepositDestination({
* idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324",
* type: "fiat",
* accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* target: {
* accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
* asset: "usdc"
* },
* metadata: {
* "customer_id": "123e4567-e89b-12d3-a456-426614174000",
* "reference": "order-12345"
* },
* fiat: {
* currency: "usd"
* }
* })
* ```
*/
public createDepositDestination(
request: CoinbaseApi.CreateDepositDestinationBody,
requestOptions?: DepositDestinationsClient.RequestOptions,
): core.HttpResponsePromise<CoinbaseApi.DepositDestination> {
return core.HttpResponsePromise.fromPromise(this.__createDepositDestination(request, requestOptions));
}
private async __createDepositDestination(
request: CoinbaseApi.CreateDepositDestinationBody,
requestOptions?: DepositDestinationsClient.RequestOptions,
): Promise<core.WithRawResponse<CoinbaseApi.DepositDestination>> {
const _metadata: core.EndpointMetadata = {
security: [{ apiKeyAuth: [] }],
method: "POST",
path: "v2/deposit-destinations",
operationId: "endpoint_depositDestinations.createDepositDestination",
headers: ["X-Idempotency-Key"],
};
const { idempotencyKey, ..._body } = request;
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest({
endpointMetadata: _metadata,
clientOptions: this._options,
request: {
method: "POST",
body: _body,
},
});
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
mergeOnlyDefinedHeaders({ "X-Idempotency-Key": idempotencyKey }),
requestOptions?.headers,
);
const _response = await core.fetcher({
url: core.url.join(
(await core.Supplier.get(this._options.baseUrl)) ??
(await core.Supplier.get(this._options.environment)) ??
environments.CoinbaseApiEnvironment.Default,
"v2/deposit-destinations",
),
method: "POST",
headers: _headers,
contentType: "application/json",
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: _body,
timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
abortSignal: requestOptions?.abortSignal,
endpointMetadata: _metadata,
fetchFn: this._options?.fetch,
logging: this._options.logging,
});
if (_response.ok) {
return { data: _response.body as CoinbaseApi.DepositDestination, rawResponse: _response.rawResponse };
}
if (_response.error.reason === "status-code") {
switch (_response.error.statusCode) {
case 400:
throw new CoinbaseApi.BadRequestError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 401:
throw new CoinbaseApi.UnauthorizedError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 403:
throw new CoinbaseApi.ForbiddenError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 404:
throw new CoinbaseApi.NotFoundError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 409:
throw new CoinbaseApi.ConflictError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 422:
throw new CoinbaseApi.UnprocessableEntityError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 500:
throw new CoinbaseApi.InternalServerError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 503:
throw new CoinbaseApi.ServiceUnavailableError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
default:
throw new errors.CoinbaseApiError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v2/deposit-destinations");
}
/**
* Get a specific deposit destination by its ID.
*
* @param {CoinbaseApi.GetDepositDestinationByIdRequest} request
* @param {DepositDestinationsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws CoinbaseApi.BadRequestError
* @throws CoinbaseApi.UnauthorizedError
* @throws CoinbaseApi.NotFoundError
* @throws CoinbaseApi.InternalServerError
*
* @example
* ```ts
* await client.depositDestinations.getDepositDestinationById({
* depositDestinationId: "depositDestination_af2937b0-9846-4fe7-bfe9-ccc22d935114"
* })
* ```
*/
public getDepositDestinationById(
request: CoinbaseApi.GetDepositDestinationByIdRequest,
requestOptions?: DepositDestinationsClient.RequestOptions,
): core.HttpResponsePromise<CoinbaseApi.DepositDestination> {
return core.HttpResponsePromise.fromPromise(this.__getDepositDestinationById(request, requestOptions));
}
private async __getDepositDestinationById(
request: CoinbaseApi.GetDepositDestinationByIdRequest,
requestOptions?: DepositDestinationsClient.RequestOptions,
): Promise<core.WithRawResponse<CoinbaseApi.DepositDestination>> {
const _metadata: core.EndpointMetadata = {
security: [{ apiKeyAuth: [] }],
method: "GET",
path: "v2/deposit-destinations/{depositDestinationId}",
operationId: "endpoint_depositDestinations.getDepositDestinationById",
};
const { depositDestinationId } = request;
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest({
endpointMetadata: _metadata,
clientOptions: this._options,
request: {
method: "GET",
},
});
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
requestOptions?.headers,
);
const _response = await core.fetcher({
url: core.url.join(
(await core.Supplier.get(this._options.baseUrl)) ??
(await core.Supplier.get(this._options.environment)) ??
environments.CoinbaseApiEnvironment.Default,
`v2/deposit-destinations/${core.url.encodePathParam(depositDestinationId)}`,
),
method: "GET",
headers: _headers,
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
abortSignal: requestOptions?.abortSignal,
endpointMetadata: _metadata,
fetchFn: this._options?.fetch,
logging: this._options.logging,
});
if (_response.ok) {
return { data: _response.body as CoinbaseApi.DepositDestination, rawResponse: _response.rawResponse };
}
if (_response.error.reason === "status-code") {
switch (_response.error.statusCode) {
case 400:
throw new CoinbaseApi.BadRequestError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 401:
throw new CoinbaseApi.UnauthorizedError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 404:
throw new CoinbaseApi.NotFoundError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
case 500:
throw new CoinbaseApi.InternalServerError(
_response.error.body as CoinbaseApi.Error_,
_response.rawResponse,
);
default:
throw new errors.CoinbaseApiError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(
_response.error,
_response.rawResponse,
"GET",
"/v2/deposit-destinations/{depositDestinationId}",
);
}
}