# Use Cases (Examples)

## Use case A — FIAT → FIAT (Payout)

1. `POST /quotes` with `railType=FIAT_FIAT`
2. `POST /payouts` with the beneficiary details and optional `quoteId`
3. Receive `payout.completed` via webhook


## Use case B — FIAT → CRYPTO (On-ramp / Payment)

Kaito routes the fiat deposit to the recipient's crypto wallet via the Kaito network.

### Request fields

| Field | Required | Description |
|  --- | --- | --- |
| `amount` | ✅ | Amount in source fiat currency |
| `sourceAccountId` | ✅ | Kaito source account ID (e.g. Brazilian PIX source) |
| `subclientId` | ✅ | The end-client receiving the stablecoin (USDC or USDT) |
| `senderWalletAddress` | ✅ | Destination crypto wallet address |
| `senderWalletChain` | ✅ | Blockchain (e.g. `ethereum`, `polygon`) |
| `senderWalletNetwork` | optional | Network name if different from chain |
| `typeOrder` | optional | `"onramp"` — inferred from `sourceAccountId` if omitted |


### Flow

1. `POST /quotes` — Kaito prices the conversion and returns `exchange`, `receiverAmount` (USDC or USDT), and `kaitoFee`.
2. `POST /payments` — Confirm the quote. Kaito initiates the on-ramp and returns deposit instructions (e.g. QR code for PIX, bank details, etc.).
3. End-client deposits fiat via the returned instructions.
4. Receive `payment.succeeded` via webhook once Kaito confirms receipt and the stablecoin (USDC or USDT) is delivered.


### What Kaito returns on confirmation

```json
{
  "orderId": "ord_...",
  "status": "pending",
  "depositInstructions": {
    "paymentRail": "pix",
    "country": "BR",
    "bankBeneficiaryName": "Kaito Technologies, Inc",
    "brCode": "00020126640014br.gov.bcb.pix..."
  },
  "financials": {
    "amount": 200.00,
    "currency": "BRL",
    "receiverAmount": 39.86,
    "receiverCurrency": "USDC",
    "exchange": 0.199279,
    "kaitoFee": 2.21,
    "userPays": 202.21
  }
}
```

## Use case C — CRYPTO → FIAT (Off-ramp / Payout)

Kaito routes stablecoins (USDC or USDT) from the sender's wallet to the beneficiary's bank account in local fiat. Settlement time may vary depending on the corridor and transaction type.

### Request fields

| Field | Required | Description |
|  --- | --- | --- |
| `amount` | ✅ | Amount in stablecoin (USDC or USDT) to send |
| `targetAccountId` | ✅ | ID of the beneficiary's bank account (pre-registered) |
| `subclientId` | ✅ | The end-client sending the stablecoin (USDC or USDT) |
| `senderWalletAddress` | ✅ | Sender's stablecoin wallet address (USDC or USDT) |
| `senderWalletChain` | ✅ | Blockchain (e.g. `ethereum`, `polygon`) |
| `senderWalletId` | optional | Internal wallet ID for managed wallets |
| `typeOrder` | optional | `"offramp"` — inferred if no `sourceAccountId` |


### Beneficiary bank account fields (pre-registered)

The fields required depend on the destination rail:

**ACH / Wire (Panama, USA):**
`accountNumber`, `routingNumber`, `accountType`, `beneficiaryName`, `addressLine1`, `city`, `stateProvinceRegion`, `postalCode`

**PIX (Brazil):**
`pixKey`, `beneficiaryName`, `bankName`

**SPEI (Mexico):**
`speiClabe`, `speiInstitutionCode`, `beneficiaryName`

**ACH (Guatemala / Colombia):**
`bankCode`, `bankAccount`, `beneficiaryFirstName`, `beneficiaryLastName`, `documentId`, `documentType`, `email`

**SWIFT (International):**
`swiftCodeBic`, `swiftAccountNumberIban`, `swiftAccountHolderName`, `swiftBankName`, `beneficiaryCountry`, `beneficiaryCity`

### Flow

1. `POST /quotes` — Kaito prices the stablecoin → local fiat conversion and locks the rate for 15 minutes. Returns `exchange`, `receiverAmount`, `kaitoFee`, `userPays`.
2. `POST /payouts` — Confirm the quote. Kaito initiates the transfer via its network to the beneficiary's bank account.
3. Receive `payout.completed` via webhook once the transfer is confirmed.


### What Kaito prices on quote

```json
{
  "quoteId": "f678d309-...",
  "status": "preview",
  "expiresAt": "2026-05-18T19:51:00Z",
  "exchange": 0.199279,
  "baseAmount": { "value": 200.00, "currency": "USDC" },  // USDC or USDT
  "receiverAmount": { "value": 39.86, "currency": "USD" },
  "kaitoFee": { "value": 0.50, "currency": "USDC" },
  "userPays": { "value": 200.50, "currency": "USDC" },
  "corridor": "CRYPTO|PA"
}
```

## Use case D — CRYPTO → CRYPTO (On-chain transfer)

1. (Optional) `POST /chain/estimate-fee`
2. `POST /payments` with `railType=CRYPTO_CRYPTO`
3. (If you manage signing) `POST /chain/tx/broadcast` with `signedTx`
4. Receive `payment.succeeded` via webhook (or poll tx status)


## Use case E — Remittance payment link creation

1. `POST /payment-links` on the Remittances API with `Idempotency-Key` (UUID v4), `x-api-key`, and `x-signature`
2. Persist `transactionId` and `remittanceUrl` returned by the API
3. Share `remittanceUrl` with the sender channel (e.g. WhatsApp or SMS)
4. Handle retries with the same `Idempotency-Key` and generate a new key for each new intent