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

# Link Wallet

> Link an on-chain wallet address to a KYC-verified customer, so their verified identity travels with that wallet's on-chain activity.



## OpenAPI

````yaml POST /v1/customers/{customerId}/wallets
openapi: 3.0.3
info:
  title: Stablepay Money API
  description: >
    The Stablepay Money API enables wallet issuers to execute stablecoin-to-fiat

    payouts across Sub-Saharan Africa via M-Pesa, mobile money, and bank
    transfers.
  version: 0.5.0
  contact:
    name: Stablepay Engineering
    email: hello@stablepay.io
servers:
  - url: https://api.stablepay.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Health
    description: Service liveness check.
  - name: FX
    description: Live FX rate conversion between USDC and local fiat currencies.
  - name: Payments
    description: Submit and track stablecoin-to-fiat payout requests.
  - name: Balances
    description: >-
      Live on-chain USDC and native token balances for the tenant's custody
      wallets.
  - name: Analytics
    description: >-
      Pre-aggregated payment analytics — volume, success rates, corridor
      breakdowns, and daily time series.
  - name: Customers
    description: |
      KYC API for DeFi wallets. Onboard and verify your end-users, then link
      their wallet addresses so verified identity travels with their on-chain
      activity.
  - name: Webhooks
    description: Register endpoints and manage outbound event delivery.
  - name: Admin
    description: >-
      Ops-only endpoints for tenant management and payment operations. Requires
      an admin-scoped API key.
paths:
  /v1/customers/{customerId}/wallets:
    post:
      tags:
        - Customers
      summary: Link a wallet
      description: >-
        Link an on-chain wallet address to a KYC-verified customer, so their
        verified identity travels with that wallet's on-chain activity.
      operationId: linkCustomerWallet
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
          example: cus_01KXG3R0X8DXTKB849FFFEPT7Y
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                walletAddress:
                  type: string
                  example: 0xAbC123...
                  description: The blockchain wallet address to link
                blockchain:
                  $ref: '#/components/schemas/Blockchain'
              required:
                - walletAddress
                - blockchain
      responses:
        '201':
          description: Wallet linked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerWallet'
        '409':
          description: This address is already linked to a customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Blockchain:
      type: string
      enum:
        - BSC
        - SOLANA
      description: Supported blockchains for onchain settlement.
    CustomerWallet:
      type: object
      properties:
        walletId:
          type: string
          example: cus_wal_01KXG3R0X8DXTKB849FFFEPT7Y
        customerId:
          type: string
          example: cus_01KXG3R0X8DXTKB849FFFEPT7Y
        walletAddress:
          type: string
          example: 0xabc123...
        blockchain:
          $ref: '#/components/schemas/Blockchain'
        createdAt:
          type: string
          format: date-time
      required:
        - walletId
        - customerId
        - walletAddress
        - blockchain
        - createdAt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        code:
          type: string
          description: Machine-readable error code.
          example: validation_error
        message:
          type: string
          description: Human-readable error message.
          example: fiatAmount must be a positive number.
      required:
        - statusCode
        - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Stablepay API key. Include as `Authorization: Bearer <key>`.

````