> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ledger.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a wallet

> Creates a new custodial crypto wallet for a customer.



## OpenAPI

````yaml /openapi.json post /v1/crypto-wallets
openapi: 3.1.0
info:
  title: Ledger API
  version: 1.0.0
  description: >-
    The Ledger API lets you issue virtual accounts and crypto wallets to your
    users and businesses. Build fintech products on top of Ledger's
    infrastructure.


    All endpoints return a consistent envelope: `{ ok: true, data: ... }` on
    success and `{ ok: false, error: { code, message } }` on failure.


    ## Base URL


    ```

    https://api.ledger.so

    ```


    ## Authentication


    Pass your API key via `Authorization: Bearer <key>` or the `X-API-Key`
    header. Keys follow the format `ld_<env>_<prefix>_<secret>` where `<env>` is
    `test` or `live`.


    ## Pagination


    List endpoints accept `limit` (default 50, max 200) and `cursor` query
    parameters. Responses include `nextCursor` when more pages are available.


    ## Idempotency


    POST endpoints accept an `Idempotency-Key` header. Reusing a key for a
    different route or method returns `409 Conflict`.
  contact:
    name: Ledger Support
    url: https://ledger.so
    email: support@ledger.so
  license:
    name: Proprietary
servers:
  - url: https://api.ledger.so
    description: Production
security:
  - BearerAuth: []
  - ApiKeyAuth: []
tags:
  - name: Health
    description: API health check
  - name: Customers
    description: Manage customers (individuals or businesses) on your platform
  - name: Crypto Wallets
    description: Create and manage custodial crypto wallets
  - name: Virtual Accounts
    description: Create and manage fiat virtual accounts with deposit instructions
  - name: Counterparties
    description: Manage customer-owned external accounts for receiving payouts
  - name: Transactions
    description: View transaction history across wallets and accounts
  - name: Rates
    description: Get current exchange rates
  - name: Transfers
    description: Move funds between currencies and payment rails
  - name: Webhooks
    description: Configure webhook endpoints to receive real-time event notifications
  - name: Reference
    description: Lookup tables for occupation and industry codes
paths:
  /v1/crypto-wallets:
    post:
      tags:
        - Crypto Wallets
      summary: Create a wallet
      description: Creates a new custodial crypto wallet for a customer.
      operationId: createWallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customerId
              properties:
                customerId:
                  type: string
                  description: The customer ID to associate this wallet with
      responses:
        '200':
          description: Wallet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletEnvelope'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    WalletEnvelope:
      type: object
      required:
        - ok
        - data
      properties:
        ok:
          type: boolean
          enum:
            - true
        data:
          $ref: '#/components/schemas/Wallet'
    Wallet:
      type: object
      required:
        - id
        - customerId
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        customerId:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          type: boolean
          enum:
            - false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - UNAUTHORIZED
                - INVALID_REQUEST
                - NOT_FOUND
                - CONFLICT
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
  responses:
    InvalidRequest:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error:
              code: INVALID_REQUEST
              message: Validation failed
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error:
              code: UNAUTHORIZED
              message: Invalid API key
    Conflict:
      description: Conflict (e.g. duplicate idempotency key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error:
              code: CONFLICT
              message: Resource already exists
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error:
              code: RATE_LIMITED
              message: Too many requests
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            ok: false
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as a Bearer token: `Authorization: Bearer ld_live_...`'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Pass your API key via the `X-API-Key` header

````