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

# Register a Customer Crypto Wallet for Transfers

> Create a new wallet and associate it with a customer.

Use this endpoint to register a customer's existing blockchain wallet address with SpherePay. SpherePay does not create or custody wallets — it links an address your customer already owns to their SpherePay profile so that transfers can be routed to or from that address. You must register at least one wallet before creating a transfer that involves crypto. The wallet address must already exist on the target network before registration.


## OpenAPI

````yaml openapi/spherepay.yaml POST /v2/wallet
openapi: 3.0.0
info:
  title: ''
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.spherepay.co
    description: Production
security:
  - bearer: []
tags: []
paths:
  /v2/wallet:
    post:
      summary: Create a Wallet
      description: Create a new wallet and associate it with a customer.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWalletDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    status: 400
                    detail: Invalid request parameters
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    status: 404
                    detail: Resource not found
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
        '422':
          description: Unprocessable Entity - Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    status: 422
                    detail: Validation failed
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
components:
  schemas:
    CreateWalletDto:
      type: object
      properties:
        customerId:
          description: The unique identifier of the customer who owns this wallet.
          example: customer_66c4168d418a410eae282b83883bdc39
          type: string
          minLength: 1
        address:
          description: >-
            The wallet address on the specified network. Must be a valid address
            format for the network.
          example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
          type: string
          minLength: 1
        network:
          description: >-
            The blockchain network for this wallet. Must be a supported crypto
            network.
          example: sol
          type: string
          enum:
            - arbitrum
            - avalanche
            - base
            - ethereum
            - optimism
            - polygon
            - sol
            - tron
      required:
        - customerId
        - address
        - network
    WalletResponseDto:
      type: object
      properties:
        id:
          description: The unique identifier of the wallet.
          example: wallet_ce745ef7f3df4b9a8bff1301ce24b045
          type: string
        address:
          description: The wallet address on the specified network.
          example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
          type: string
        network:
          description: The blockchain network for this wallet.
          example: sol
          type: string
          enum:
            - sol
            - fogo
            - ethereum
            - optimism
            - arbitrum
            - polygon
            - base
            - avalanche
            - sui
            - noble
            - sei
            - tron
            - starknet
            - aptos
            - hyperliquid
        customerId:
          description: The unique identifier of the customer who owns this wallet.
          example: customer_66c4168d418a410eae282b83883bdc39
          type: string
        created:
          description: The ISO 8601 timestamp when the wallet was created.
          example: '2025-01-01T00:00:00.000Z'
          type: string
        updated:
          description: The ISO 8601 timestamp when the wallet was last updated.
          example: '2025-01-01T00:00:00.000Z'
          type: string
      required:
        - id
        - address
        - network
        - customerId
        - created
        - updated
    ProblemDetailsDto:
      type: object
      properties:
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              detail:
                type: string
              pointer:
                type: string
              parameter:
                type: string
              header:
                type: string
            required:
              - detail
        correlationId:
          type: string
      required:
        - status
        - detail
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````