# Transfer funds between two tenants within the same omnibus

Moves an amount from a source tenant to a destination tenant within the same omnibus by recording a cross-account entry in the Accounting service. Asynchronous: accepts the request, durably persists the operation, starts a Temporal workflow (validate → reserve → post to Accounting → finalize), and returns 202 with status=PENDING immediately. Poll GET .../internal-transfers/{operationId} for the terminal status. A required, per-transfer Idempotency-Key makes retries safe — reuse the same key to retry a transfer, use a new key for a new transfer. See InternalTransferStatus for the meaning of each status.

Endpoint: POST /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/internal-transfers

## Path parameters:

  - `domainId` (string, required)

  - `omnibusId` (string, required)

  - `tenantId` (string, required)

## Header parameters:

  - `Idempotency-Key` (string, required)
    Required. A client-chosen, per-transfer token, unique within the source tenant; reuse the exact same value on every retry of the same transfer. A missing header is rejected with 400, as is a blank value. The operationId is derived deterministically from (domainId, sourceTenantId, key), so reusing the key for a different payload returns 409, and different source tenants may reuse the same key without collision.

## Request fields (application/json):

  - `destTenantId` (string, required)
    Destination tenant ID (funds are credited to this tenant)

  - `amount` (string, required)
    Positive integer in the ticker's smallest unit (e.g., wei for ETH, satoshis for BTC, drops for XRP). No leading zeros; zero is not allowed.

  - `tickerId` (string, required)
    Identifier of the ticker to transfer

  - `ledgerId` (string, required)
    Identifier of the blockchain ledger; must match on both source and destination

## Response 202 fields (application/json):

  - `operationId` (string, required)
    Operation ID for this internal transfer

  - `transferId` (string, required)
    Transfer ID for this movement

  - `status` (string, required)
    Enum: "PENDING", "COMPLETED", "FAILED", "PENDING_VERIFICATION"

  - `sourceTenantId` (string, required)
    Source tenant (debited)

  - `destTenantId` (string, required)
    Destination tenant (credited)

  - `amount` (string, required)
    Positive integer in the ticker's smallest unit

  - `tickerId` (string, required)

  - `ledgerId` (string, required)