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

````