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

# Add Wallet

> API reference for adding wallet payout methods

Adds a new wallet payout method (either merchant-owned or customer-specific).

* Include `customer_id` to create for a specific customer
* Omit `customer_id` to create merchant-owned wallet

### Request Body:

```json theme={null}
{
  "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e", // optional
  "label": "usdc wallet", // optional
  "wallet_address": "0x7fD41923E23DcE32d1A346e96558dA89f89DD1aB",
  "network": "erc20",
  "currency": "USDC"
}
```


## OpenAPI

````yaml POST /payout/methods/wallets
openapi: 3.0.0
info:
  title: 'StableStack: API Service'
  description: "# Overview\n\n##  Introduction\n\nStableStack offers an API first, last mile payment orchestration + liquidity router built with stablecoins. Stablecoin layer integrated into your existing payment flow, with smart accounts and blockchain abstraction. Go between digital and fiat currencies in minutes.\n\n## Getting Help\n\nWe're excited to have you build with us! If you're integrating, we will set up a communication channel. This will enable our teams to easily collaborate and ensure you launch as quickly as possible.\n\nPlease reach out to us at\_[hello@stablestack.xyz](https://mailto:hello@stablestack.xyz)\_for any questions or concerns."
  version: 1.0.0
servers:
  - url: https://api-staging.stablestack.com/api
    description: StableStack API
security: []
tags:
  - name: customers
  - name: customers > kyc
  - name: payouts
  - name: banks
  - name: transactions
  - name: wallets
  - name: assets
  - name: swap
paths:
  /payout/methods/wallets:
    post:
      tags:
        - payouts
      summary: Add wallet payout method
      description: >
        Adds a new wallet payout method (either merchant-owned or
        customer-specific).

        - Include customer_id to create for a specific customer

        - Omit customer_id to create merchant-owned wallet
      parameters:
        - name: x-api-key
          in: header
          schema:
            type: string
          required: true
          example: ''
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - wallet_address
                - network
                - currency
              properties:
                type:
                  type: string
                  enum:
                    - WALLET
                  default: WALLET
                  description: Must be 'WALLET' for this endpoint
                customer_id:
                  type: string
                  nullable: true
                  description: Required only for customer-specific payout methods
                  example: 85b148ab-3f6b-4d55-917f-3c8de668a48e
                label:
                  type: string
                  maxLength: 100
                  example: usdc wallet
                wallet_address:
                  type: string
                  example: 0x9iu41923E23DcE32d1A346e96558dA89f89DD1aB
                network:
                  type: string
                  enum:
                    - erc20
                    - polygon
                  example: erc20
                currency:
                  type: string
                  enum:
                    - USDC
                  example: USDC
      responses:
        '201':
          description: Wallet added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 46a75b50-4bdc-4f59-b891-602dc247effe
                      type:
                        type: string
                        example: WALLET
                      currency:
                        type: string
                        example: USDC
                      label:
                        type: string
                        example: usdc wallet
                      wallet_address:
                        type: string
                        example: 0x9iu41923E23DcE32d1A346e96558dA89f89DD1aB
                      network:
                        type: string
                        example: erc20
                      created_at:
                        type: string
                        format: date-time
                        example: '2025-05-12T15:50:31.679Z'
                      updated_at:
                        type: string
                        format: date-time
                        example: '2025-05-12T15:50:31.679Z'
                      customer_id:
                        type: string
                        nullable: true
                        example: 85b148ab-3f6b-4d55-917f-3c8de668a48e
                  message:
                    type: string
                    example: Payout method added successfully
              examples:
                merchantWallet:
                  value:
                    status: success
                    data:
                      id: 10530920-81eb-451e-a205-16f9ddb1949a
                      type: WALLET
                      currency: USDC
                      label: usdc wallet
                      wallet_address: 0x9iu41923E23DcE32d1A346e96558dA89f89DD1aB
                      network: erc20
                      created_at: '2025-05-19T19:22:34.511Z'
                      updated_at: '2025-05-19T19:22:34.511Z'
                      customer_id: null
                    message: Merchant payout method added successfully!
                customerWallet:
                  value:
                    status: success
                    data:
                      id: 46a75b50-4bdc-4f59-b891-602dc247effe
                      type: WALLET
                      currency: USDC
                      label: usdc wallet
                      wallet_address: 0x9iu41923E23DcE32d1A346e96558dA89f89DD1aB
                      network: erc20
                      created_at: '2025-05-12T15:50:31.679Z'
                      updated_at: '2025-05-12T15:50:31.679Z'
                      customer_id: 85b148ab-3f6b-4d55-917f-3c8de668a48e
                    message: Customer payout method added successfully!
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: failed
                  message:
                    type: string
                    example: Validation error
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: field
                        value:
                          type: string
                          example: ''
                        msg:
                          type: string
                          example: Wallet address is required
                        path:
                          type: string
                          example: wallet_address
                        location:
                          type: string
                          example: body

````