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

# Orígenes de tasa de payouts y cotizaciones FIFO

> Entiende el pricing lot, blend y spot y consulta una cotización FIFO indicativa

export const EnvUrls = ({lang = "en"}) => {
  const T = {
    en: {
      test: "Test",
      live: "Live",
      hint: "Same API on both environments — build against test first, then go live by swapping the base URL and the key.",
      guide: "Environments and testing",
      href: "/en/environment-testing"
    },
    es: {
      test: "Test",
      live: "Live",
      hint: "La misma API en ambos ambientes — construye primero contra test y pasa a live cambiando la URL base y la key.",
      guide: "Entorno y pruebas",
      href: "/es/environment-testing"
    },
    zh: {
      test: "Test",
      live: "Live",
      hint: "两个环境的 API 完全一致——先在 test 环境构建，再通过切换基础 URL 和密钥上线。",
      guide: "环境与测试",
      href: "/zh/environment-testing"
    }
  };
  const t = T[lang] || T.en;
  const row = (label, url, keyPattern, badgeCls) => <div className="flex flex-wrap items-center gap-2 px-3 py-2">
      <span className={"rounded px-1.5 py-0.5 text-xs font-semibold uppercase tracking-wide " + badgeCls}>
        {label}
      </span>
      <code className="text-xs">{url}</code>
      <span className="text-xs text-gray-400 dark:text-zinc-500">·</span>
      <code className="text-xs">{keyPattern}</code>
    </div>;
  return <div className="my-4 rounded-xl border border-gray-200 dark:border-zinc-700 divide-y divide-gray-200 dark:divide-zinc-700 text-sm not-prose">
      {row(t.test, "https://cryptobank.qbank.cl/platform", "pk_test_...", "bg-amber-100 text-amber-800 dark:bg-amber-900/40 dark:text-amber-300")}
      {row(t.live, "https://api.qbank.cl/platform", "pk_...", "bg-emerald-100 text-emerald-800 dark:bg-emerald-900/40 dark:text-emerald-300")}
      <p className="px-3 py-2 text-xs text-gray-500 dark:text-zinc-400 m-0">
        {t.hint} <a href={t.href}>{t.guide} →</a>
      </p>
    </div>;
};

<EnvUrls lang="es" />

## Origen de tasa y cotización FIFO indicativa

Las respuestas de payout pueden incluir `rate_source` para explicar de dónde
salió la tasa de mercado ejecutada:

| Valor | Significado |
| - | - |
| `lot` | El monto local fue cubierto completamente por el inventario fiat FIFO de la organización. |
| `blend` | El inventario FIFO cubrió una parte y el resto usó spot. |
| `spot` | No se usó inventario FIFO elegible. |

El campo está disponible en la creación y el detalle cuando se carga la
atribución. Puede faltar en filas históricas o de listado. No cambia el débito,
la comisión ni el contrato del webhook.

### Cotización de payout vigente en `GET /v1/rates`

La respuesta de tasas para la cuenta mantiene el nombre `rate` para la punta
de payout. Es la cotización de mercado ejecutable para el próximo payout: la
plataforma revisa el lote FIFO abierto más antiguo de la moneda del país.
Cuando existe inventario elegible, `rate_source` es `lot`; si no, usa spot y
`rate_source` es `spot`. Si falla la lectura del inventario, también cae a
`spot`; el débito del payout sigue siendo fail-closed.

`payin_rate` es la cotización del lado de depósitos. En USDT v1 puede estar
respaldada por lotes payin habilitados, fondeados por trades `buy_crypto`
liquidados; `payin_rate_source` informa `lot` o `spot`. Create/detail de payin
puede incluir `rate_source` cuando cargó una cotización. Los payins con tarjeta
siguen usando spot. El endpoint para administradores de organización expone la
misma distinción con `payout_rate`, `payin_rate`, `rate_source` y
`payin_rate_source`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "rates": {
    "chile": {
      "currency": "CLP",
      "rate": "910.896551",
      "rate_source": "lot",
      "payin_rate": "955.10",
      "payin_rate_source": "spot"
    }
  }
}
```

Este valor por país es una vista indicativa del próximo payout. Un payout más
grande puede consumir varios lotes; usa el `lot_quote` opt-in para una
cotización indicativa por monto y conserva la respuesta del payout junto con
el webhook final como registro autoritativo de la ejecución.

Para previsualizar una cotización indicativa que considere inventario, agrega
`currency` y `amount` a `GET /v1/rates`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.qbank.cl/platform/v1/rates?currency=CLP&amount=100000.00"   -H "Authorization: Bearer <token>"
```

La respuesta normal de tasas puede traer:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "lot_quote": {
    "currency": "CLP",
    "amount": "100000.00000000",
    "market_rate": "13.42150000",
    "rate_source": "blend",
    "marked_rate": "13.28728500",
    "indicative": true
  }
}
```

`lot_quote` es de solo lectura e indicativo. La ejecución bloquea el inventario
dentro de la transacción del débito, por lo que un payout concurrente puede
cambiar el resultado. `marked_rate` es opcional. Los errores de validación son
valores dentro de la respuesta `200`: `invalid_amount`,
`currency_not_supported` o `quote_unavailable`.

La cotización no garantiza el precio futuro. La respuesta del payout y el
evento final `payout_status_changed` son la fuente autoritativa. Para payins,
la cotización queda fijada antes del crédito asíncrono; el consumo FIFO registra
la atribución al acreditar. Un faltante cae a spot y genera una alerta operativa
sin cambiar el crédito cotizado.

### Estados de la cotización

| Estado | Significado | Siguiente acción |
| - | - | - |
| `indicative` | La cotización se calculó sin locks de ejecución. | Crea el payout con la misma clave y lee su `rate_source` ejecutado. |
| `executed` | La respuesta del payout contiene la atribución autoritativa. | Guarda la respuesta y el webhook final para conciliar. |
| `error` | La respuesta contiene `invalid_amount`, `currency_not_supported` o `quote_unavailable`. | Corrige los datos o repite la cotización de solo lectura; no crees un payout desde el error. |

### Llave de tasa EUR para SEPA

El único corredor de enrutamiento Europa (`EU`)/EUR/`sepa` comparte
una sola llave de tasa: `sepa`, con `currency: "EUR"`. El catálogo de payouts
devuelve `country: "EU"` para esta fila, mientras el país real del beneficiario
sale del IBAN. El fee de payout y el spread FX resuelven sobre la fila de
pricing `EU`. `rate_source` sigue describiendo la cotización ejecutable
(`lot` o `spot`) y `payin_rate` sigue siendo spot del lado de depósitos.

<AccordionGroup>
  <Accordion title="Does this quote reserve inventory?">
    No. It is read-only and indicative. The payout debit transaction locks and
    consumes inventory atomically.
  </Accordion>

  <Accordion title="What should I store for reconciliation?">
    Store the payout response and its final `payout_status_changed` event. Use
    `rate_source` as the execution provenance; do not treat `lot_quote` as a
    guarantee.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.