> ## Documentation Index > Fetch the complete documentation index at: https://docs.conduit.financial/llms.txt > Use this file to discover all available pages before exploring further. # Create a wallet > Creates a new blockchain wallet for the customer on the specified chain. By default the customer must first claim non-custodial control via POST /v2/customers/{id}/wallets/claim-non-custodial; for organizations enabled for custodial wallets, the account is provisioned on the first call to this endpoint with no claim required. An idempotency-key header is required. For post-activation non-custodial accounts, returns 202 with a ceremonyId and a verificationUrl when admin approval is needed. While the provisioning activity is still being set up there is no approval link to return, so the call is refused with a retryable 409 CEREMONY_IN_FLIGHT — retry shortly and the 202 arrives once the link exists. The admin approval link is also delivered on the `wallet_ceremony.awaiting_admin_approval` webhook. ## OpenAPI ````yaml https://api.sandbox.conduit.financial/v2/api-docs/openapi.json post /customers/{customerId}/wallets openapi: 3.0.0 info: title: Conduit Sandbox API description: >- **Sandbox API** — clients integrate against this surface to exercise happy and unhappy paths without consuming real KYC/PSP credits or moving real money. Customer KYC, banking partners, and crypto custody are stubbed; org-level KYB runs against real providers. Simulation endpoints under `/v2/sandbox/*` drive specific scenarios. Internal and portal endpoints are excluded from this spec. version: '2.0' contact: {} servers: - url: https://api.sandbox.conduit.financial/v2 description: Sandbox - url: https://api.conduit.financial/v2 description: Production security: - api-key: [] tags: - name: Customers - name: Registered Addresses - name: Wallets - name: Wallet Signers - name: Signing Quorum - name: Virtual Accounts - name: Applications - name: Documents - name: Verifications - name: Signing Requests - name: Transactions - name: Payouts - name: Whitelist Recipients - name: Orders - name: Quotes - name: RFIs - name: Webhook Endpoints - name: Webhook Deliveries - name: Webhook Event Types - name: Features - name: Customer Onboarding - name: Markup - name: Sandbox paths: /customers/{customerId}/wallets: post: tags: - Wallets summary: Create a wallet description: >- Creates a new blockchain wallet for the customer on the specified chain. By default the customer must first claim non-custodial control via POST /v2/customers/{id}/wallets/claim-non-custodial; for organizations enabled for custodial wallets, the account is provisioned on the first call to this endpoint with no claim required. An idempotency-key header is required. For post-activation non-custodial accounts, returns 202 with a ceremonyId and a verificationUrl when admin approval is needed. While the provisioning activity is still being set up there is no approval link to return, so the call is refused with a retryable 409 CEREMONY_IN_FLIGHT — retry shortly and the 202 arrives once the link exists. The admin approval link is also delivered on the `wallet_ceremony.awaiting_admin_approval` webhook. operationId: WalletsCustomerController_createWallet_v2 parameters: - name: customerId required: true in: path schema: type: string - name: Idempotency-Key in: header description: >- Caller-generated unique key that lets the server safely replay this request. The cached response is returned for 5 minutes on any retry with the same key from the same API principal. Required on every state-changing money-moving or resource-creating POST. required: true schema: type: string pattern: ^[A-Za-z0-9_.:-]{1,128}$ minLength: 1 maxLength: 128 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWalletDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/WalletResponse' '202': description: '' content: application/json: schema: $ref: '#/components/schemas/WalletCreateCeremonyPendingResponse' '400': description: >- **INVALID_OID_FORMAT**: A path or query parameter expected a valid object identifier but received a value that does not match the expected format. **VALIDATION_ERROR**: The request body or query parameters failed validation. One or more fields have invalid values, missing required properties, or incorrect types. Multipart file uploads that fail at the multipart-parser layer (unexpected form-field name, too many parts) carry an extra 'field' member naming the offending form-field. **MALFORMED_JSON**: The request body could not be parsed as JSON. Bodies declared as 'application/json' — and bodies with no Content-Type header, which are assumed to be JSON — must contain syntactically valid JSON. **IDEMPOTENCY_KEY_REQUIRED**: This endpoint requires an Idempotency-Key header to prevent duplicate processing. Generate a unique key per logical request and resend the request. **IDEMPOTENCY_KEY_INVALID**: The Idempotency-Key header value did not match the required shape (1-128 characters, letters / digits / underscore / dot / colon / hyphen). **IDEMPOTENCY_BODY_TOO_NESTED**: The request body exceeds the maximum nesting depth allowed by the idempotency fingerprint hasher. Deeply-nested arrays or objects are rejected as a malformed payload. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorDto' example: type: INVALID_OID_FORMAT title: Invalid Object ID Format status: 400 detail: >- A path or query parameter expected a valid object identifier but received a value that does not match the expected format. resolution: >- Verify that all IDs in the request URL and query parameters are correctly formatted. IDs are typically prefixed strings like 'cus_...', 'app_...', or 'doc_...'. docs: https://conduit-v2.mintlify.app/errors#invalid-oid-format instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '401': description: >- **API_KEY_MISSING**: The request did not include an API key. All API requests must be authenticated. **API_KEY_INVALID**: The provided API key is not recognized or has been revoked. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: API_KEY_MISSING title: API Key Missing status: 401 detail: >- The request did not include an API key. All API requests must be authenticated. resolution: >- Include your API key in the 'x-api-key' header with every request. docs: https://conduit-v2.mintlify.app/errors#api-key-missing instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '403': description: >- **API_KEY_READ_ONLY**: This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: API_KEY_READ_ONLY title: API Key Is Read-Only status: 403 detail: >- This API key has read-only access and cannot perform write operations. Read-only keys may make read requests (GET, HEAD, OPTIONS) only. resolution: >- Use a read-write API key for this request, or have an organization admin mint one from the dashboard. docs: https://conduit-v2.mintlify.app/errors#api-key-read-only instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '404': description: >- **CUSTOMER_NOT_FOUND**: No customer exists with the specified ID, or the customer belongs to a different organization. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: CUSTOMER_NOT_FOUND title: Customer Not Found status: 404 detail: >- No customer exists with the specified ID, or the customer belongs to a different organization. resolution: >- Verify the customer ID is correct. Use the list customers endpoint to find valid customer IDs for your organization. docs: https://conduit-v2.mintlify.app/errors#customer-not-found instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '409': description: >- **IDEMPOTENCY_KEY_CONFLICT**: The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original. **IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS**: A request with this idempotency key is already being processed and has not yet completed. Concurrent requests with the same key are rejected to prevent duplicate execution. **WALLET_PROVIDER_CONFLICT**: The customer's wallet account is in a state — suspended, frozen, or errored — that cannot create wallets. This is distinct from an account that is still provisioning. **WALLET_ACCOUNT_NOT_READY**: The customer's wallet account is still provisioning and is not yet active, so wallet addresses cannot be created on it. Either a non-custodial claim is in flight and the account has not been created yet, or the account exists and is awaiting signer passkey enrollment. **WALLET_CUSTODY_NOT_CLAIMED**: The customer's wallet account is custodial, but custodial wallets are not enabled for this organization. Wallet addresses cannot be issued on a custodial account unless the custodial wallet path is enabled, and a custodial account cannot be claimed as non-custodial. **WALLET_AWAITING_ADMIN_APPROVAL**: This wallet is being provisioned through a ceremony that is awaiting admin approval. **CEREMONY_IN_FLIGHT**: A ceremony for this account is already in progress and the request would duplicate it. This happens for a signer roster change (a concurrent promote or demote of the same signer), or for a wallet create when a wallet for the same account is already being created (for example, requesting a second EVM chain while the first EVM chain's wallet is still being set up — the EVM chains share one address). The request is rejected until the in-flight ceremony finishes. **CONFLICT**: The request conflicts with the current state of the resource. This usually means a duplicate or a state transition that is not allowed. **WALLET_CLIENT_REFERENCE_IMMUTABLE**: The customer already holds a wallet on this chain, and a create cannot set or change its clientReferenceId. A wallet takes its clientReferenceId when it is created, and no endpoint changes it afterwards. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: IDEMPOTENCY_KEY_CONFLICT title: Idempotency Key Conflict status: 409 detail: >- The idempotency key was previously used with a different request body. Idempotency keys are bound to the exact request shape — replays must match the original. resolution: >- Use a fresh idempotency key for the new request, or replay the original request unchanged. docs: >- https://conduit-v2.mintlify.app/errors#idempotency-key-conflict instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '415': description: >- **UNSUPPORTED_MEDIA_TYPE**: The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: UNSUPPORTED_MEDIA_TYPE title: Unsupported Media Type status: 415 detail: >- The request carries a body with a Content-Type this endpoint cannot parse. JSON endpoints accept 'application/json'; a body with no Content-Type header at all is assumed to be JSON. File-upload endpoints accept only 'multipart/form-data' — JSON or undeclared bodies are rejected there. resolution: >- Send the request body with the 'Content-Type: application/json' header. For file uploads, use 'Content-Type: multipart/form-data' — upload endpoints accept no other body type. docs: https://conduit-v2.mintlify.app/errors#unsupported-media-type instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '422': description: >- **WALLET_NO_PROVIDER_ACCOUNT**: The customer does not yet have a wallet account on the underlying provider. Wallet addresses cannot be created until the customer claims non-custodial control. **WALLET_PROVISIONING_REJECTED**: The custody provider rejected the wallet creation; no wallet was created and no funds were moved. **CRYPTO_WALLET_CONSENSUS_REQUIRED**: This wallet operation needs a customer admin's approval before it can complete; it could not be finished synchronously. No funds were moved and no wallet was created. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: WALLET_NO_PROVIDER_ACCOUNT title: Wallet Account Not Provisioned status: 422 detail: >- The customer does not yet have a wallet account on the underlying provider. Wallet addresses cannot be created until the customer claims non-custodial control. resolution: >- Submit a non-custodial claim via POST /v2/customers/:id/wallets/claim-non-custodial to provision the wallet account, then retry creating the wallet. docs: >- https://conduit-v2.mintlify.app/errors#wallet-no-provider-account instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '429': description: >- **RATE_LIMITED**: Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses. content: application/json: schema: $ref: '#/components/schemas/RateLimitedErrorDto' example: type: RATE_LIMITED title: Rate Limited status: 429 detail: >- Too many requests. This error is returned by three independent checks: the per-organization bucket applied to every authenticated API request; the per-IP bucket applied to unauthenticated traffic before an API key is validated; and the per-IP bucket applied when repeated invalid API keys are submitted from the same address. Honor the Retry-After header (also exposed as retryAfterSeconds in the body) before retrying. Current limits and remaining budget are visible in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on rate-limited route responses. resolution: >- Sleep until Retry-After seconds have elapsed, then retry. For sustained workloads exceeding the per-organization defaults, request a rate-limit increase through your support contact. docs: https://conduit-v2.mintlify.app/errors#rate-limited instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' retryAfterSeconds: 3 '500': description: >- **INTERNAL_ERROR**: An unexpected error occurred while processing your request. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: INTERNAL_ERROR title: Internal Error status: 500 detail: An unexpected error occurred while processing your request. resolution: >- Retry the request after a brief delay. If the error persists, contact support and include the correlationId from the error response for investigation. docs: https://conduit-v2.mintlify.app/errors#internal-error instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' '503': description: >- **CHAIN_ACTIVATION_UNAVAILABLE**: The wallet record was created, but the on-chain account behind it could not be opened because the funding account Conduit sponsors new accounts from is not available. No funds were moved. The error detail names the chain. content: application/json: schema: $ref: '#/components/schemas/ProblemDetailDto' example: type: CHAIN_ACTIVATION_UNAVAILABLE title: Chain Activation Unavailable status: 503 detail: >- The wallet record was created, but the on-chain account behind it could not be opened because the funding account Conduit sponsors new accounts from is not available. No funds were moved. The error detail names the chain. resolution: >- Retry the same request shortly. The wallet keeps the same ID and the retry completes the on-chain setup. If it persists, contact support. docs: >- https://conduit-v2.mintlify.app/errors#chain-activation-unavailable instance: /v2/... correlationId: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe timestamp: '2026-01-15T09:30:00.000Z' components: schemas: CreateWalletDto: type: object properties: chain: type: string enum: - ethereum - base - polygon - solana - tron - stellar description: Blockchain network for the new wallet clientReferenceId: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ description: >- Client-supplied reference, unique per resource within your organization. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces. required: - chain additionalProperties: false WalletResponse: type: object properties: id: type: string pattern: ^wlt_[0-9A-Za-z]{22}$ description: Unique wallet identifier example: wlt_2xKjF9mQb7vN4hL1pR3w8t chain: type: string enum: - ethereum - base - polygon - solana - tron - stellar description: Blockchain network of the wallet example: ethereum address: type: string description: On-chain wallet address, null while provisioning example: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18' nullable: true status: description: Current wallet lifecycle status type: string enum: - pending - active - disabled custodyModel: description: >- `non_custodial` — the customer co-signs each payout via the verify URL (see `requiresUserSignature` on payouts). `custodial` is a return-only value for legacy/operational wallets. Omitted until the custody model is determined. type: string enum: - non_custodial - custodial rotatedAt: description: Timestamp of the last key rotation, omitted until rotated type: string format: date-time example: '2026-01-15T09:30:00.000Z' replacedByWalletId: description: >- ID of the wallet that replaced this one after rotation, omitted until rotated type: string pattern: ^wlt_[0-9A-Za-z]{22}$ clientReferenceId: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ description: >- Client-supplied reference, unique per resource within your organization. 1-255 characters from A-Za-z, 0-9, underscore, hyphen, colon, and period — no spaces. balances: type: array items: type: object properties: available: type: object properties: code: type: string enum: - USD - EUR - GBP - CHF - JPY - CAD - AUD - NZD - SGD - HKD - CNY - KRW - INR - BRL - MXN - ARS - CLP - COP - PEN - ZAR - NGN - KES - GHS - EGP - AED - SAR - ILS - TRY - PLN - CZK - HUF - SEK - NOK - DKK - THB - IDR - MYR - PHP - VND - TWD - USDC - USDT - DAI - EURC - PYUSD - BTC - ETH - SOL - TRX - XLM description: Asset code (USDC, USD, etc.) chain: description: Chain when the asset is on-chain; omitted for fiat. type: string enum: - ethereum - base - solana - polygon - arbitrum - optimism - avalanche - tron - stellar - bsc - bitcoin amount: type: string description: Decimal string, asset-precision rounded required: - code - amount additionalProperties: false pending: type: object properties: code: type: string enum: - USD - EUR - GBP - CHF - JPY - CAD - AUD - NZD - SGD - HKD - CNY - KRW - INR - BRL - MXN - ARS - CLP - COP - PEN - ZAR - NGN - KES - GHS - EGP - AED - SAR - ILS - TRY - PLN - CZK - HUF - SEK - NOK - DKK - THB - IDR - MYR - PHP - VND - TWD - USDC - USDT - DAI - EURC - PYUSD - BTC - ETH - SOL - TRX - XLM description: Asset code (USDC, USD, etc.) chain: description: Chain when the asset is on-chain; omitted for fiat. type: string enum: - ethereum - base - solana - polygon - arbitrum - optimism - avalanche - tron - stellar - bsc - bitcoin amount: type: string description: Decimal string, asset-precision rounded required: - code - amount additionalProperties: false frozen: type: object properties: code: type: string enum: - USD - EUR - GBP - CHF - JPY - CAD - AUD - NZD - SGD - HKD - CNY - KRW - INR - BRL - MXN - ARS - CLP - COP - PEN - ZAR - NGN - KES - GHS - EGP - AED - SAR - ILS - TRY - PLN - CZK - HUF - SEK - NOK - DKK - THB - IDR - MYR - PHP - VND - TWD - USDC - USDT - DAI - EURC - PYUSD - BTC - ETH - SOL - TRX - XLM description: Asset code (USDC, USD, etc.) chain: description: Chain when the asset is on-chain; omitted for fiat. type: string enum: - ethereum - base - solana - polygon - arbitrum - optimism - avalanche - tron - stellar - bsc - bitcoin amount: type: string description: Decimal string, asset-precision rounded required: - code - amount additionalProperties: false required: - available - pending - frozen description: >- Balance for one asset on an account: available, pending, and frozen buckets all in the same asset. description: Wallet balances by asset createdAt: type: string format: date-time description: Timestamp when the wallet was created example: '2026-01-15T09:30:00.000Z' updatedAt: type: string format: date-time description: Timestamp when the wallet was last updated example: '2026-01-15T09:30:00.000Z' required: - id - chain - address - status - balances - createdAt - updatedAt WalletCreateCeremonyPendingResponse: type: object properties: ceremonyId: type: string pattern: ^wcm_[0-9A-Za-z]{22}$ description: Ceremony ID for the pending wallet provisioning verificationUrl: type: string description: URL for admin approval of the ceremony required: - ceremonyId - verificationUrl ValidationErrorDto: type: object properties: type: type: string description: Machine-readable error code example: CUSTOMER_NOT_FOUND title: type: string description: Human-readable error type label example: Customer Not Found status: type: number description: HTTP status code example: 404 detail: type: string description: Human-readable explanation of this occurrence example: Customer with id cus_034A0gCCVsxdV2PjHLx9k1 not found resolution: type: string description: What the developer should do to resolve this error example: >- Verify the customer ID. Check you are using the correct API key for this organization. docs: type: string description: URL to error documentation example: https://conduit-v2.mintlify.app/errors#customer-not-found instance: type: string description: Request path that produced the error example: /v2/customers/cus_034A0gCCVsxdV2PjHLx9k1 correlationId: description: Request correlation ID example: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe type: string timestamp: type: string description: ISO 8601 UTC timestamp example: '2026-04-27T20:00:00.000Z' details: description: >- Additional structured data for domain-specific errors (e.g. missing field lists, pair info) errors: type: array items: type: object properties: pointer: type: string description: JSON pointer to the invalid field example: /email detail: type: string description: What is wrong with this field example: Invalid email format allowedValues: description: The values this field accepts, when it is a closed set example: - ach - fedwire - rtp type: array items: type: string category: description: >- Class of blocker (requirements-validator output only). 'field' = form-field gap, 'document' = missing or insufficient document (including per-UBO document slots), 'individual' = required person missing. example: field type: string enum: - field - document - individual required: - pointer - detail required: - type - title - status - detail - resolution - docs - instance - timestamp ProblemDetailDto: type: object properties: type: type: string description: Machine-readable error code example: CUSTOMER_NOT_FOUND title: type: string description: Human-readable error type label example: Customer Not Found status: type: number description: HTTP status code example: 404 detail: type: string description: Human-readable explanation of this occurrence example: Customer with id cus_034A0gCCVsxdV2PjHLx9k1 not found resolution: type: string description: What the developer should do to resolve this error example: >- Verify the customer ID. Check you are using the correct API key for this organization. docs: type: string description: URL to error documentation example: https://conduit-v2.mintlify.app/errors#customer-not-found instance: type: string description: Request path that produced the error example: /v2/customers/cus_034A0gCCVsxdV2PjHLx9k1 correlationId: description: Request correlation ID example: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe type: string timestamp: type: string description: ISO 8601 UTC timestamp example: '2026-04-27T20:00:00.000Z' details: description: >- Additional structured data for domain-specific errors (e.g. missing field lists, pair info) required: - type - title - status - detail - resolution - docs - instance - timestamp RateLimitedErrorDto: type: object properties: type: type: string description: Machine-readable error code example: CUSTOMER_NOT_FOUND title: type: string description: Human-readable error type label example: Customer Not Found status: type: number description: HTTP status code example: 404 detail: type: string description: Human-readable explanation of this occurrence example: Customer with id cus_034A0gCCVsxdV2PjHLx9k1 not found resolution: type: string description: What the developer should do to resolve this error example: >- Verify the customer ID. Check you are using the correct API key for this organization. docs: type: string description: URL to error documentation example: https://conduit-v2.mintlify.app/errors#customer-not-found instance: type: string description: Request path that produced the error example: /v2/customers/cus_034A0gCCVsxdV2PjHLx9k1 correlationId: description: Request correlation ID example: 00469ea4-52c1-4ffa-bd05-9f28b236a5fe type: string timestamp: type: string description: ISO 8601 UTC timestamp example: '2026-04-27T20:00:00.000Z' details: description: >- Additional structured data for domain-specific errors (e.g. missing field lists, pair info) retryAfterSeconds: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Seconds to wait before retrying example: 3 required: - type - title - status - detail - resolution - docs - instance - timestamp - retryAfterSeconds securitySchemes: api-key: type: apiKey in: header name: x-api-key ````