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

# Transfer

> This endpoint starts a transfer of funds between customers or external wallets.



## OpenAPI

````yaml /openapi/api-production.yaml post /transactions/transfer
openapi: 3.1.0
info:
  version: 1.0.0
  title: Lumx API
  description: >-
    A cross-border banking API with instant settlements and unmatched liquidity,
    powered by stablecoins.
servers:
  - url: https://api.lumx.io
  - url: https://api-sandbox.lumx.io
security: []
paths:
  /transactions/transfer:
    post:
      tags:
        - Transactions
      summary: Transfer
      description: >-
        This endpoint starts a transfer of funds between customers or external
        wallets.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionTransferRequest'
      responses:
        '202':
          description: Transfer transaction started successfully.
          content:
            application/json:
              example:
                id: 123e4567-e89b-12d3-a456-426614174004
                customerId: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                type: TRANSFER
                request:
                  currency: USDC
                  from: 123e4567-e89b-12d3-a456-426614174001
                  to: 123e4567-e89b-12d3-a456-426614174002
                  amount: '1000.000000'
                state:
                  status: PENDING
                metadata: {}
              schema:
                allOf:
                  - $ref: '#/components/schemas/TransactionTransferResponse'
                  - $ref: '#/components/schemas/TransactionTimestamps'
      security:
        - apiKey: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: >-
        Optional UUID v4 idempotency key. If you resend the same key with a
        different request body, the API returns a 409 error. Cached responses
        include the header `X-Idempotency-Cached: true`. Keys expire after 24
        hours.
  schemas:
    TransactionTransferRequest:
      type: object
      properties:
        currency:
          type: string
          enum:
            - USDC
            - USDT
          description: Transfer's currency.
          example: USDC
        from:
          type: string
          format: uuid
          description: Customer's unique identifier that will send the funds.
          example: 3c90c3cc-0d44-4b50-8888-8dd25736052a
        to:
          oneOf:
            - type: string
              format: uuid
              title: customer
              description: Customer's unique identifier that will receive the funds.
              example: 980dc26b-42fd-4044-8a42-2271d20a2eb9
            - type: string
              format: wallet-address
              title: address
              description: Customer's wallet address that will receive the funds.
              example: '0x1234567890123456789012345678901234567890'
        amount:
          type: string
          description: Transfer's amount.
          example: '10000.000000'
        blockchain:
          type: string
          enum:
            - ETHEREUM
            - BASE
            - TRON
            - POLYGON
          description: >-
            Target blockchain for the transaction. If not provided, the
            project's default blockchain will be used.
          example: POLYGON
        metadata:
          type: object
          description: >-
            Optional metadata object to attach to the transaction. Accepts any
            valid JSON object.
          additionalProperties: true
          example:
            orderId: ord_789
            source: checkout
      required:
        - currency
        - amount
        - from
        - to
    TransactionTransferResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Transfer operation's unique identifier.
          example: 123e4567-e89b-12d3-a456-426614174000
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: 123e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          description: Transfer operation's type.
          enum:
            - TRANSFER
          example: TRANSFER
        request:
          type: object
          properties:
            currency:
              type: string
              description: Transfer's currency.
              example: USDC
            from:
              type: string
              format: uuid
              description: Customer's unique identifier that will send the funds.
              example: 123e4567-e89b-12d3-a456-426614174000
            to:
              oneOf:
                - type: string
                  format: uuid
                  title: customer
                  description: Customer's unique identifier that will receive the funds.
                  example: 980dc26b-42fd-4044-8a42-2271d20a2eb9
                - type: string
                  format: wallet-address
                  title: address
                  description: Customer's wallet address that will receive the funds.
                  example: '0x1234567890123456789012345678901234567890'
            amount:
              type: string
              description: Transfer's amount.
              example: '10000.000000'
        state:
          type: object
          description: Transfer operation's current state. See examples for more details.
        metadata:
          type: object
          description: Metadata object attached to the transaction.
          additionalProperties: true
          example:
            orderId: ord_789
            source: checkout
        createdAt:
          type: string
          format: date-time
          description: Creation date and time (UTC).
          example: '2024-03-20T15:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update date and time (UTC).
          example: '2024-03-20T15:30:05Z'
    TransactionTimestamps:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: Creation date and time (UTC).
        updatedAt:
          type: string
          format: date-time
          description: Last update date and time (UTC).
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Bearer authentication header on the format `Bearer <API_KEY>`.

````