openapi: 3.1.0
info:
  title: ChicksX Payments API
  version: 1.0.0
  description: >
    REST API that provides an interface to ChicksX cryptocurrency exchange
    ecosystem. This API enables merchants to offer their users cryptocurrency
    purchases, sales, and swaps through a simple integration.


    ## 🧪 Interactive Demo


    We provide an interactive demo tool to test the complete SDK integration:


    **[https://demos.chicksx.com](https://demos.chicksx.com)**


    This demo allows you to:

    - Test SDK configuration with different operation types

    - Generate public access tokens

    - Simulate webhook events

    - View code examples in real-time


    # Getting Started


    ### Prerequisites


    Before you can integrate with the ChicksX Payments API, you need to obtain
    your merchant credentials:


    - **merchant-api-key**: Your unique API key for authentication

    - **merchant-client-id**: Your merchant client identifier


    **Important**: If you don't have these credentials yet, please contact our
    support team at **support@chicksx.com**


    ### Security Notice


    🔒 **All endpoints requiring `merchant-api-key` and `merchant-client-id`
    headers MUST be called from your backend server only.** These credentials
    should never be exposed in client-side applications (web browsers, mobile
    apps, etc.) as they provide full access to your merchant account.


    # SDK Integration Flow


    To integrate the ChicksX SDK into your application, follow these steps:


    ### Step 1: Obtain Merchant Credentials


    Contact support@chicksx.com to receive:

    - `merchant-api-key`

    - `merchant-client-id`


    ### Step 2: Create a Public Access Token (Server-Side)


    From your **backend server**, make a request to create a public access
    token:


    ```bash

    POST https://develop-api.chicksx.com/v1/public_token/create

    Headers:
      merchant-api-key: your-api-key
      merchant-client-id: your-client-id
    ```


    This returns a public access token that can be safely used in your
    client-side application.


    ### Step 3: Embed the SDK Script (Client-Side)


    In your frontend application, add the ChicksX SDK script tag with the
    required parameters:


    ```html

    <script
    src="https://develop-api.chicksx.com/v1/sdk/chicksx.js?merchantId=your-merchant-id&env=dev&accessToken=your-public-token&baseCurrency=cad&targetCurrency=usdt&baseAmount=100&paymentMethod=interac"></script>

    ```


    Then configure and initialize the SDK:


    ```html

    <script>
      window.chicksX.configure({
        merchantId: 'your-merchant-id',
        env: 'dev',
        accessToken: 'your-public-token',
        operationType: 'buy',
        baseCurrency: 'cad',
        targetCurrency: 'usdt',
        baseAmount: 100,
        paymentMethod: 'interac',
        walletAddress: '0xYourWalletAddressOptional'
      });
      window.chicksX.init();
    </script>

    ```


    Note: `window.chicksX.init()` opens the payment popup/modal. You typically
    want to call it in response to a user action (e.g., a button click) to avoid
    unexpected popups:


    ```html

    <button id="payButton">Pay with ChicksX</button>

    <script>
      document.getElementById('payButton').addEventListener('click', function () {
        window.chicksX.init();
      });
    </script>

    ```


    ### Step 4: SDK Configuration Parameters


    **Required Parameters:**

    - `merchantId` - Your merchant identifier

    - `env` - Environment (`dev`, `staging`, or `prod`)

    - `accessToken` - The public token obtained from Step 2


    **Optional Parameters:**

    - `operationType` - Type of operation: `buy` (default), `sell`, `swap-fiat`,
    or `swap-crypto`

    - `baseCurrency` - Source currency code (default: based on merchant config)

    - `targetCurrency` - Target cryptocurrency code (default: based on merchant
    config)

    - `baseAmount` - Amount in base currency

    - `targetAmount` - Amount in target currency

    - `paymentMethod` - Payment method identifier (e.g., `interac`,
    `cash-in-mail`, `cash-in-person`, `bill-payment`, `balance`)

    - `walletAddress` - Cryptocurrency wallet address


    ### Operation Types and URL Paths


    The `operationType` parameter determines the URL path structure for the
    payment flow:


    | Operation Type | Description |

    |---------------|-------------|

    | `buy` | Buy cryptocurrency with fiat |

    | `sell` | Sell cryptocurrency for fiat |

    | `swap-fiat` | Swap between fiat currencies |

    | `swap-crypto` | Swap between cryptocurrencies |


    **Payment Methods by Operation:**

    - **Buy**: `interac`, `cash-in-mail`, `cash-in-person`, `bill-payment`,
    `balance`

    - **Sell**: `interac`, `cash-in-mail`, `cash-in-person`

    - **Swap Fiat**: `cash-in-mail`, `cash-in-person`

    - **Swap Crypto**: No payment method required (crypto-to-crypto)


    ## Wallet Management


    The API provides comprehensive wallet management capabilities for storing
    and managing user cryptocurrency wallets associated with your merchant
    account.


    # Webhooks


    ChicksX uses webhooks to notify your application when events occur in your
    account. Webhooks are particularly useful for asynchronous events like order
    status changes.


    ## Setting Up Webhooks


    To receive webhook notifications:


    1. **Contact Support**: Email support@chicksx.com to register your webhook
    endpoint URL

    2. **Provide Your URL**: Supply a publicly accessible HTTPS endpoint that
    can receive POST requests

    3. **Environment-Specific**: You can configure different webhook URLs for
    development, staging, and production environments


    ## Webhook Events


    ChicksX sends the following webhook event types:


    ### OrderCreated

    Triggered when a new order is created in the system.


    ```json

    {
      "eventType": "OrderCreated",
      "details": {
        "orderId": 1092114,
        "status": "pending",
        "paymentMethod": "Interac E-Transfer",
        "fulfilled": false,
        "totalPrice": 100.00,
        "totalPriceCurrency": "CAD",
        "exchangeDetails": {
          "baseCurrency": "CAD",
          "amountReceived": 100.00,
          "targetCurrency": "BTC",
          "amountToSend": 0.00112180,
          "operationType": "B"
        }
      }
    }

    ```


    ### OrderFulfillment

    Triggered when an order the order fulfills.


    ```json

    {
      "eventType": "OrderFulfillment",
      "details": {
        "orderId": 1092114,
        "status": "completed",
        "paymentMethod": "Interac E-Transfer",
        "fulfilled": true,
        "totalPrice": 100.00,
        "totalPriceCurrency": "CAD",
        "exchangeDetails": {
          "baseCurrency": "CAD",
          "amountReceived": 100.00,
          "targetCurrency": "BTC",
          "amountToSend": 0.00112180,
          "operationType": "B"
        }
      }
    }

    ```


    ## Webhook Payload Structure


    | Field | Type | Description |

    |-------|------|-------------|

    | `eventType` | string | Event type: `OrderCreated` or `OrderFulfillment` |

    | `details.orderId` | integer | Unique order identifier |

    | `details.status` | string | Current order status |

    | `details.paymentMethod` | string | Payment method used |

    | `details.fulfilled` | boolean | Whether the order has been fulfilled |

    | `details.totalPrice` | number | Total price of the order |

    | `details.totalPriceCurrency` | string | Currency of the total price |

    | `details.exchangeDetails.baseCurrency` | string | Source currency |

    | `details.exchangeDetails.amountReceived` | number | Amount received in
    base currency |

    | `details.exchangeDetails.targetCurrency` | string | Target currency |

    | `details.exchangeDetails.amountToSend` | number | Amount to send in target
    currency |

    | `details.exchangeDetails.operationType` | string | Operation type: `B`
    (Buy), `S` (Sell), `SF` (Swap Fiat), `SC` (Swap Crypto) |


    ## Handling Webhooks


    Your webhook endpoint should:


    1. **Return 200 OK**: Respond with HTTP 200 status to acknowledge receipt

    2. **Process Asynchronously**: Handle the webhook data asynchronously to
    avoid timeouts

    3. **Be Idempotent**: Handle duplicate webhook deliveries gracefully (use
    `orderId` as unique identifier)

    4. **Validate Data**: Verify the webhook data matches expected formats


    ### Example Webhook Handler (Node.js)


    ```javascript

    app.post('/webhook/chicksx', (req, res) => {
      const { eventType, details } = req.body;
      
      console.log(`Received ${eventType} for order ${details.orderId}`);
      
      switch (eventType) {
        case 'OrderCreated':
          // Handle new order
          handleNewOrder(details);
          break;
        case 'OrderFulfillment':
          // Handle order status update
          handleOrderUpdate(details);
          break;
      }
      
      // Always respond with 200 to acknowledge receipt
      res.status(200).send('OK');
    });

    ```


    ## Security Considerations


    - Use HTTPS endpoints only

    - Validate incoming webhook data

    - Consider implementing signature verification (contact support for details)

    - Store webhook data for audit purposes
  contact:
    name: ChicksX Support
    email: support@chicksx.com
  license:
    name: Proprietary
servers:
  - url: https://develop-api.chicksx.com/v1
    description: Development server
  - url: https://staging-api.chicksx.com/v1
    description: Staging server
  - url: https://api.chicksx.com/v1
    description: Production server
security:
  - MerchantAuth: []
components:
  securitySchemes:
    MerchantAuth:
      type: apiKey
      in: header
      name: merchant-api-key
      description: >
        Merchant API authentication requires two headers:

        - `merchant-api-key`: Your API key

        - `merchant-client-id`: Your client ID


        **Security Warning**: Never expose these credentials in client-side
        code. Use only from secure backend servers.
  parameters:
    MerchantClientId:
      name: merchant-client-id
      in: header
      required: true
      schema:
        type: string
      description: Your merchant client identifier (must be kept secure)
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: string
          description: Result code indicating the operation status
          example: OK
        data:
          type: object
          description: Response data payload
        message:
          type: string
          description: Human-readable response message
          example: Operation completed successfully
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: INVALID_INPUT
        message:
          type: string
          description: Error message
          example: Invalid JSON in request body
    PublicTokenRequest:
      type: object
      properties:
        scope:
          type: array
          items:
            type: string
          description: Array of permission scopes for the token
          example:
            - wallet.read
            - merchant.read
        sessionId:
          type: string
          description: Optional session identifier for tracking
          example: session-123abc
    PublicTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT access token for SDK authentication
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        tokenType:
          type: string
          description: Token type
          example: Bearer
        expiresIn:
          type: integer
          description: Token lifetime in seconds
          example: 3600
        expiresAt:
          type: integer
          description: Unix timestamp when token expires
          example: 1696531200
        scope:
          type: array
          items:
            type: string
          description: Granted permission scopes
          example:
            - wallet.read
            - merchant.read
        jti:
          type: string
          description: Unique token identifier (JWT ID)
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    WalletRequest:
      type: object
      required:
        - walletAddress
        - currencyCode
      properties:
        walletAddress:
          type: string
          description: Cryptocurrency wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
        currencyCode:
          type: string
          description: Currency code (e.g., BTC, ETH, USDT)
          example: USDT
        networkCode:
          type: string
          description: Blockchain network code (e.g., ERC20, TRC20, BEP20)
          example: ERC20
    WalletResponse:
      type: object
      properties:
        id:
          type: integer
          description: Unique wallet identifier
          example: 1001
        user:
          type: object
          properties:
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
        walletAddress:
          type: string
          description: Cryptocurrency wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
        currencyCode:
          type: string
          description: Currency code
          example: USDT
        networkCode:
          type: string
          description: Network code
          example: ERC20
    WalletLookupResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the lookup was successful
          example: true
        message:
          type: string
          description: Result message
          example: Wallet found
        wallet:
          oneOf:
            - $ref: '#/components/schemas/WalletResponse'
            - type: 'null'
        availableNetworks:
          type: array
          items:
            type: string
          description: List of available networks for this currency
          example:
            - ERC20
            - TRC20
            - BEP20
        requiresNetworkCode:
          type: boolean
          description: Whether network code is required for this currency
          example: true
paths:
  /public_token/create:
    post:
      summary: Create public access token
      description: >
        Creates a public access token for SDK authentication. This endpoint must
        be called from your **secure backend server** using your merchant
        credentials.


        The returned access token can be safely used in client-side applications
        to authenticate with the ChicksX SDK.


        **Security**: Never expose your merchant-api-key or merchant-client-id
        in client-side code.
      operationId: createPublicToken
      tags:
        - SDK Authentication
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicTokenRequest'
            examples:
              defaultScopes:
                summary: Default scopes
                value:
                  scope:
                    - wallet.read
                    - merchant.read
              withSession:
                summary: With session tracking
                value:
                  scope:
                    - wallet.read
                    - merchant.read
                  sessionId: user-session-abc123
      responses:
        '201':
          description: Public token created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PublicTokenResponse'
              examples:
                success:
                  summary: Successful token creation
                  value:
                    code: OK
                    data:
                      accessToken: >-
                        eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjaGlja3N4LWFwaSIsInN1YiI6Im1lcmNoYW50LWRlbW8iLCJhdWQiOiJjaGlja3N4LXNkayIsImV4cCI6MTY5NjUzNDgwMCwiaWF0IjoxNjk2NTMxMjAwLCJqdGkiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJlbnZpcm9ubWVudCI6InNhbmRib3giLCJzY29wZSI6WyJ3YWxsZXQucmVhZCIsIm1lcmNoYW50LnJlYWQiXX0.signature
                      tokenType: Bearer
                      expiresIn: 3600
                      expiresAt: 1696534800
                      scope:
                        - wallet.read
                        - merchant.read
                      jti: f47ac10b-58cc-4372-a567-0e02b2c3d479
        '400':
          description: Bad request - Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidJson:
                  summary: Invalid JSON
                  value:
                    code: INVALID_INPUT
                    message: Invalid JSON in request body
        '401':
          description: Unauthorized - Invalid or missing merchant credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                serverError:
                  summary: Token generation failed
                  value:
                    message: Token generation failed
  /sdk/chicksx.js:
    get:
      summary: Get ChicksX SDK Script
      description: >
        Retrieves the ChicksX SDK JavaScript file with embedded configuration.
        This script should be embedded in your client-side application using a
        `<script>` tag.


        **This endpoint does not require merchant authentication headers** as
        it's meant to be called from client-side applications.


        ### Example Usage


        ```html

        <script
        src="https://develop-api.chicksx.com/v1/sdk/chicksx.js?merchantId=demo-merchant&env=dev&accessToken=your-public-token&baseCurrency=cad&targetCurrency=usdt&baseAmount=100&paymentMethod=interac"></script>

        ```
      operationId: getSdkScript
      tags:
        - SDK
      security: []
      parameters:
        - name: merchantId
          in: query
          required: true
          schema:
            type: string
          description: Your merchant identifier
          example: demo-merchant
        - name: env
          in: query
          required: true
          schema:
            type: string
            enum:
              - dev
              - staging
              - prod
          description: Target environment
          example: dev
        - name: accessToken
          in: query
          required: true
          schema:
            type: string
          description: Public access token obtained from /public_token/create endpoint
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        - name: operationType
          in: query
          required: false
          schema:
            type: string
            enum:
              - buy
              - sell
              - swap-fiat
              - swap-crypto
            default: buy
          description: |
            Type of transaction operation:
            - `buy`: Buy cryptocurrency with fiat currency (default)
            - `sell`: Sell cryptocurrency for fiat currency
            - `swap-fiat`: Swap between fiat currencies
            - `swap-crypto`: Swap between cryptocurrencies
          example: buy
        - name: baseCurrency
          in: query
          required: false
          schema:
            type: string
          description: Source currency code (fiat)
          example: cad
        - name: targetCurrency
          in: query
          required: false
          schema:
            type: string
          description: Target cryptocurrency code
          example: usdt
        - name: baseAmount
          in: query
          required: false
          schema:
            type: number
          description: Amount in base currency
          example: 100
        - name: targetAmount
          in: query
          required: false
          schema:
            type: number
          description: Amount in target currency
          example: 73.45
        - name: paymentMethod
          in: query
          required: false
          schema:
            type: string
          description: Payment method identifier (e.g., interac, paypal, cash-in-mail)
          example: interac
        - name: walletAddress
          in: query
          required: false
          schema:
            type: string
          description: Cryptocurrency wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
      responses:
        '200':
          description: SDK script returned successfully
          content:
            application/javascript:
              schema:
                type: string
                description: JavaScript SDK code with embedded configuration
        '500':
          description: Error serving script
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error serving script
  /wallets:
    post:
      summary: Create Wallet
      description: >
        Creates a new cryptocurrency wallet entry for a user. This endpoint must
        be called from your **secure backend server**.


        **Security**: Requires merchant authentication headers.
      operationId: createWallet
      tags:
        - Wallet Management
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletRequest'
            examples:
              ethereum:
                summary: Ethereum wallet
                value:
                  walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
                  currencyCode: ETH
                  networkCode: ERC20
              bitcoin:
                summary: Bitcoin wallet
                value:
                  walletAddress: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
                  currencyCode: BTC
                  networkCode: BTC
      responses:
        '201':
          description: Wallet created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WalletResponse'
              examples:
                success:
                  summary: Wallet created
                  value:
                    code: OK
                    message: Wallet created successfully
                    data:
                      id: 1001
                      walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
                      currencyCode: USDT
                      networkCode: ERC20
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingFields:
                  summary: Missing required fields
                  value:
                    code: INVALID_INPUT
                    message: Wallet address and currency code are required
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: Get All Wallets
      description: >
        Retrieves all cryptocurrency wallets associated with your merchant
        account. This endpoint must be called from your **secure backend
        server**.


        **Security**: Requires merchant authentication headers.
      operationId: getAllWallets
      tags:
        - Wallet Management
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
      responses:
        '200':
          description: Wallets retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/WalletResponse'
              examples:
                success:
                  summary: List of wallets
                  value:
                    code: OK
                    data:
                      - id: 1001
                        walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
                        currencyCode: USDT
                        networkCode: ERC20
                      - id: 1002
                        walletAddress: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
                        currencyCode: BTC
                        networkCode: BTC
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /wallets/search:
    get:
      summary: Search Wallet
      description: >
        Searches for a wallet by currency code and optionally by network code.
        This endpoint must be called from your **secure backend server**.


        If multiple networks exist for a currency and no network code is
        provided, the response will include available networks.


        **Security**: Requires merchant authentication headers.
      operationId: getWallet
      tags:
        - Wallet Management
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
        - name: currencyCode
          in: query
          required: true
          schema:
            type: string
          description: Currency code to search for
          example: USDT
        - name: networkCode
          in: query
          required: false
          schema:
            type: string
          description: Network code (required if currency supports multiple networks)
          example: ERC20
      responses:
        '200':
          description: Wallet search completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WalletLookupResponse'
              examples:
                found:
                  summary: Wallet found
                  value:
                    code: OK
                    data:
                      success: true
                      message: Wallet found
                      wallet:
                        id: 1001
                        walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
                        currencyCode: USDT
                        networkCode: ERC20
                      availableNetworks:
                        - ERC20
                        - TRC20
                        - BEP20
                      requiresNetworkCode: true
                multipleNetworks:
                  summary: Multiple networks available
                  value:
                    code: OK
                    data:
                      success: false
                      message: >-
                        Multiple networks available for USDT. Please specify
                        networkCode.
                      wallet: null
                      availableNetworks:
                        - ERC20
                        - TRC20
                        - BEP20
                      requiresNetworkCode: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingCurrency:
                  summary: Missing currency code
                  value:
                    code: INVALID_INPUT
                    message: Currency code is required
                notFound:
                  summary: Wallet not found
                  value:
                    code: NOT_FOUND
                    message: No wallet found for the specified criteria
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /wallets/{id}:
    get:
      summary: Get Wallet by ID
      description: >
        Retrieves a specific wallet by its unique identifier. This endpoint must
        be called from your **secure backend server**.


        **Security**: Requires merchant authentication headers.
      operationId: getWalletById
      tags:
        - Wallet Management
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Wallet ID
          example: 1001
      responses:
        '200':
          description: Wallet retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WalletResponse'
              examples:
                success:
                  summary: Wallet details
                  value:
                    code: OK
                    data:
                      id: 1001
                      user:
                        firstName: John
                        lastName: Doe
                      walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
                      currencyCode: USDT
                      networkCode: ERC20
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidId:
                  summary: Invalid wallet ID
                  value:
                    code: INVALID_INPUT
                    message: Valid wallet ID is required
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Update Wallet
      description: >
        Updates an existing wallet's information. This endpoint must be called
        from your **secure backend server**.


        **Security**: Requires merchant authentication headers.
      operationId: updateWallet
      tags:
        - Wallet Management
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Wallet ID
          example: 1001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletRequest'
            examples:
              updateAddress:
                summary: Update wallet address
                value:
                  walletAddress: '0x8ba1f109551bd432803012645ac136ddd64dba72'
                  currencyCode: USDT
                  networkCode: ERC20
      responses:
        '200':
          description: Wallet updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/WalletResponse'
              examples:
                success:
                  summary: Update successful
                  value:
                    message: Wallet updated successfully
                    data:
                      id: 1001
                      walletAddress: '0x8ba1f109551bd432803012645ac136ddd64dba72'
                      currencyCode: USDT
                      networkCode: ERC20
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidId:
                  summary: Invalid wallet ID
                  value:
                    code: INVALID_INPUT
                    message: Valid wallet ID is required
                missingFields:
                  summary: Missing required fields
                  value:
                    code: INVALID_INPUT
                    message: Wallet address and currency code are required
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete Wallet
      description: >
        Deletes a wallet by its ID. This endpoint must be called from your
        **secure backend server**.


        **Security**: Requires merchant authentication headers.
      operationId: deleteWallet
      tags:
        - Wallet Management
      security:
        - MerchantAuth: []
      parameters:
        - $ref: '#/components/parameters/MerchantClientId'
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Wallet ID
          example: 1001
      responses:
        '200':
          description: Wallet deleted successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: 'null'
              examples:
                success:
                  summary: Deletion successful
                  value:
                    data: null
                    message: Wallet deleted successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidId:
                  summary: Invalid wallet ID
                  value:
                    code: INVALID_INPUT
                    message: Valid wallet ID is required
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
tags:
  - name: SDK Authentication
    description: Endpoints for SDK authentication and token management
  - name: SDK
    description: SDK script delivery
  - name: Wallet Management
    description: Cryptocurrency wallet management operations
  - name: Webhooks
    description: Webhook event notifications for order status changes
