---
title: "Create an external wallet"
method: POST
path: "/v1/external-wallets"
tags: ["External Wallets"]
---

# Create an external wallet

`POST /v1/external-wallets`

Create an external wallet for a customer. This is an asynchronous flow.

## Headers

- `X-API-Key` string

## Request body

- CreateExternalWalletDto
  - `customerId` string, required — Customer ID
  - `counterpartyId` string — Existing counterparty ID for third-party recipient wallets. If not provided, we'll upsert a new counterparty.
  - `walletAddress` string, required — Wallet address
  - `chains` string[] — Supported chains
  - `currencies` string[] — Supported currencies
  - `externalReference` string — Client-provided external reference for mapping to your system (UUID v4 or CUID recommended)
  - `isThirdParty` boolean — Whether this account belongs to a third party (not the customer). Defaults to false.
  - `custodyType` 'SELF_HOSTED' | 'ANCHORAGE' | 'BINANCE' | 'BITGO' | 'CIRCLE' | 'COINBASE' | 'FIREBLOCKS' | 'GEMINI' | 'KRAKEN' | 'ROBINHOOD' | 'OTHER_EXCHANGE' — Wallet custody type used for provider custodian mapping. Defaults to SELF_HOSTED.
  - `metadata` AccountMetadataDto
    - `nickname` string — Account nickname
    - `purpose` string — Account purpose
    - `tags` string[] — Account tags
  - `beneficiaryType` 'INDIVIDUAL' | 'BUSINESS' — Beneficiary type for third-party recipients. Required when creating a new third-party counterparty.
  - `beneficiaryName` string — Beneficiary legal name for third-party recipients. Required when creating a new third-party counterparty.
  - `beneficiaryAddress` AddressDto
    - `addressLine1` string, required — Address line 1
    - `addressLine2` string — Address line 2 (apartment, suite, etc.)
    - `city` string, required — City
    - `state` string — State / Province
    - `postalCode` string, required — Postal code / ZIP code. May be empty for countries without a postal-code system, including the United Arab Emirates.
    - `country` string, required — Country code (ISO 3166-2)
    - `transliterated` TransliteratedAddressDto
      - `addressLine1` string — Transliterated address line 1 (Latin characters)
      - `addressLine2` string — Transliterated address line 2 (Latin characters)
      - `city` string — Transliterated city (Latin characters)
      - `state` string — Transliterated state/province (Latin characters)

## Response `201`

External wallet created and submitted for async review

- ExternalWalletResponseDto
  - `id` string, required — Account ID
  - `customerId` string, required — Customer ID
  - `counterpartyId` string, nullable — Counterparty ID when this is a third-party recipient wallet
  - `type` 'EXTERNAL_WALLET', required — Account type
  - `status` 'IN_REVIEW' | 'ACTIVE' | 'CLOSED', required — Account status
  - `metadata` AccountMetadataDto
    - `nickname` string — Account nickname
    - `purpose` string — Account purpose
    - `tags` string[] — Account tags
  - `walletAddress` string, required — Wallet address
  - `addressType` 'EVM' | 'TRON' | 'BITCOIN' | 'SOLANA', required — Wallet address type
  - `chains` string[] — Supported blockchain chains
  - `currencies` array[], required
    - string[] — Supported currencies
  - `custodyType` 'SELF_HOSTED' | 'ANCHORAGE' | 'BINANCE' | 'BITGO' | 'CIRCLE' | 'COINBASE' | 'FIREBLOCKS' | 'GEMINI' | 'KRAKEN' | 'ROBINHOOD' | 'OTHER_EXCHANGE' — Wallet custody type used for provider custodian mapping.
  - `createdAt` string, date-time, required — Account creation date
  - `updatedAt` string, date-time, required — Account last update date
  - `created` boolean — Whether this account was newly created in this request or returned from an existing match

## Other responses

- `401` — Unauthorized - Invalid or missing authentication credentials

---

[API](https://skmtc.dev/infinite/apis/infinite-api.md) · [All operations](https://skmtc.dev/infinite/apis/infinite-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/infinite/infinite-api/revisions/5426f2706725/schema)