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

# Create Wallet

Creates a new wallet for a user. The wallet address must be valid for the specified virtual machine type (`EVM` or `SVM`).

***

## Important Notes

* Wallet address validation is performed based on the `vmType`. An EVM address cannot be used with `SVM`, and vice versa.

***

## Error Codes

### Common Errors

| HTTP Status | Code                   | Message                            |
| ----------- | ---------------------- | ---------------------------------- |
| 401         | `UNAUTHORIZED`         | "API Key is missing"               |
| 401         | `UNAUTHORIZED`         | "Invalid API Key format"           |
| 401         | `UNAUTHORIZED`         | "Invalid API Key"                  |
| 403         | `INVALID_PARTNER_FLOW` | "The partner has an invalid flow." |

### User Ownership Errors

| HTTP Status | Code           | Message                                              |
| ----------- | -------------- | ---------------------------------------------------- |
| 401         | `UNAUTHORIZED` | "Partner information is required for this operation" |
| 401         | `UNAUTHORIZED` | "User is not associated with the partner"            |

### Endpoint-Specific Errors

| HTTP Status | Code                             | Message                                                  |
| ----------- | -------------------------------- | -------------------------------------------------------- |
| 400         | `INVALID_USER_INPUT_ERROR`       | "Invalid User Input"                                     |
| 400         | `UserOnRampWalletDuplicateError` | "A wallet with this address and VM type already exists." |


## OpenAPI

````yaml reference/openapi/WalletAddressPartnerV2Controller_createUserWallet.json POST /api/partner/v2/users/{userId}/wallets
openapi: 3.0.0
info:
  title: Capa Partner API - V2
  description: >-
    Partner API for integrating cryptocurrency on-ramp and off-ramp services
    using Capa's infrastructure. Enable your users to seamlessly convert between
    fiat and crypto.
  version: v2
  contact: {}
servers:
  - url: https://staging-api.capa.fi
  - url: https://production-api.capa.fi
security: []
paths:
  /api/partner/v2/users/{userId}/wallets:
    post:
      tags:
        - user
      operationId: WalletAddressPartnerV2Controller_createUserWallet
      parameters:
        - name: userId
          required: true
          in: path
          description: The userId of the user
          schema:
            example: 8374f327-38bd-4b0b-b8a7-2524599eb903
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vmType:
                  description: The virtual machine type for the wallet
                  example: EVM
                  enum:
                    - EVM
                    - SVM
                  type: string
                walletAddress:
                  type: string
                  description: The wallet address
                  example: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
                alias:
                  type: string
                  description: The alias name for the wallet
              required:
                - vmType
                - walletAddress
                - alias
      responses:
        '201':
          description: Creates a new wallet for a user
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Wallet ID
                        example: 8374f327-38bd-4b0b-b8a7-2524599eb903
                      userId:
                        type: string
                        description: User ID
                        example: 8374f327-38bd-4b0b-b8a7-2524599eb903
                      walletAddress:
                        type: string
                        description: The blockchain wallet address
                        example: '0x4d2f3d8f83b6f2f8e0f3f4f3f3f3f3f3f3f3f3f3'
                      alias:
                        type: string
                        description: The alias name for the wallet
                        example: My Polygon Wallet
                      vmType:
                        description: The virtual machine type
                        example: EVM
                        enum:
                          - EVM
                          - SVM
                        type: string
                      enabled:
                        type: boolean
                        description: Whether the wallet is enabled
                        example: true
                      createdAt:
                        type: string
                        description: Wallet creation date
                        example: '2025-05-08T18:00:00Z'
                    required:
                      - id
                      - userId
                      - walletAddress
                      - alias
                      - vmType
                      - enabled
                      - createdAt
              example:
                success: true
                data:
                  id: 8374f327-38bd-4b0b-b8a7-2524599eb903
                  userId: 8374f327-38bd-4b0b-b8a7-2524599eb903
                  walletAddress: '0x4d2f3d8f83b6f2f8e0f3f4f3f3f3f3f3f3f3f3f3'
                  alias: My Polygon Wallet
                  vmType: EVM
                  enabled: true
                  createdAt: '2025-05-08T18:00:00Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: INVALID_USER_INPUT_ERROR
                message: Invalid User Input
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: API Key is missing
                UNAUTHORIZED_2:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Invalid API Key format
                UNAUTHORIZED_3:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Invalid API Key
                UNAUTHORIZED_4:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: Partner information is required for this operation
                UNAUTHORIZED_5:
                  value:
                    success: false
                    code: UNAUTHORIZED
                    message: User is not associated with the partner
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UserOnRampWalletDuplicateError:
                  value:
                    success: false
                    code: UserOnRampWalletDuplicateError
                    message: A wallet with this address and VM type already exists.
                UserOnRampWalletLimitError:
                  value:
                    success: false
                    code: UserOnRampWalletLimitError
                    message: Only {limit} wallet addresses can be saved per account.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                code: INTERNAL_SERVER_ERROR
                message: Internal server error
      security:
        - PartnerApiKey: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: Optional per-field validation details.
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
      required:
        - success
        - code
        - message
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      in: header
      name: partner-api-key
      description: API key for the affiliated partner performing the request.

````