Create an inventory lot

Cria um Inventory Lot a partir de uma cotação usage = INVENTORY, AVAILABLE e não expirada. Esta é a única operação de aceite: em uma chamada a LB Pay fecha com a MSB a taxa e o volume, cria a promessa de pagamento em USDC e cria o lote, que nasce ACTIVE com taxa, volume e validade da cotação. A execução do câmbio acontece em cada withdrawal que consome o lote. A cotação passa a USED (FxQuote.inventoryId). Cada chamada cria um lote novo e independente; lotes nunca são agregados. O lote não depende de withdrawal e é consumido depois por withdrawals com funding.mode = INVENTORY. Idempotente por Idempotency-Key. Cliente sem a modalidade INVENTORY habilitada recebe FUNDING_MODE_NOT_ENABLED.

Cancelamento, tratamento do volume não utilizado na expiração e cobrança da obrigação em USDC serão comunicados antes da disponibilidade geral.

POST /v1/inventories

Create an inventory lot from an INVENTORY quote

cURL

curl --request POST \
  --url https://api.lbpay.example.com/v1/inventories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "quoteId": "qt_01JA1X",
  "externalId": "inventory-2026-11-04-001"
}
'

201

{
  "inventoryId": "inv_01JA2B",
  "quoteId": "<string>",
  "status": "ACTIVE",
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "rate": "5.40000000",
  "total": {
    "source": {
      "currency": "USD",
      "amount": "1000.00"
    },
    "destination": {
      "currency": "USD",
      "amount": "1000.00"
    }
  },
  "available": {
    "source": {
      "currency": "USD",
      "amount": "1000.00"
    },
    "destination": {
      "currency": "USD",
      "amount": "1000.00"
    }
  },
  "reserved": {
    "source": {
      "currency": "USD",
      "amount": "1000.00"
    },
    "destination": {
      "currency": "USD",
      "amount": "1000.00"
    }
  },
  "used": {
    "source": {
      "currency": "USD",
      "amount": "1000.00"
    },
    "destination": {
      "currency": "USD",
      "amount": "1000.00"
    }
  },
  "expiresAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "externalId": "<string>",
  "referenceRate": "5.43210000",
  "spread": {
    "percentage": "0.75",
    "amount": {
      "currency": "USD",
      "amount": "7.50"
    }
  },
  "pendingSettlement": {
    "currency": "USD",
    "amount": "1000.00"
  },
  "settlementId": "<string>",
  "metadata": {}
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

Unique key to prevent duplicate creation or execution.

Required string length: 8 - 128

Body

application/json

quoteId · string · required

Cotação usage = INVENTORY, AVAILABLE e não expirada. Define taxa, volume e validade do lote.

externalId · string

ID da MSB para o lote. Opcional; se informado, único por cliente entre Inventories.

Maximum string length: 128

metadata · object

Response

201

application/json

Inventory Lot criado

Inventory Lot: câmbio contratado antecipadamente pela MSB e promessa de pagamento em USDC. Cada aceite de cotação INVENTORY cria um lote independente, com taxa, volume e validade próprios. total = available + reserved + used. A obrigação em USDC existe independentemente de withdrawals e se refere ao volume não utilizado; o evento e a data de apuração e cobrança serão comunicados antes da disponibilidade geral.

inventoryId · string · required

Example:

"inv_01JA2B"

quoteId · string · required

Cotação INVENTORY que originou o lote.

status · enum<string> · required

ACTIVE: dentro da validade, com volume disponível. DEPLETED: sem volume disponível (todo reservado ou utilizado); volta a ACTIVE se uma reserva for liberada dentro da validade. EXPIRED: passou de expiresAt; não aceita novos withdrawals. O tratamento do volume remanescente após a expiração será comunicado antes da disponibilidade geral. Enum extensível.

Available options: ACTIVE, DEPLETED, EXPIRED

fromCurrency · enum<string> · required

Available options: USD

toCurrency · enum<string> · required

Available options: BRL

rate · string · required

Taxa contratada entre a MSB e a LB Pay (BRL por USD), já com o spread. Aplicada a todas as remessas do lote.

Pattern: ^[0-9]+(\.[0-9]{1,8})?$

Example:

"5.40000000"

total · object · required

Volume contratado.

Show child attributes

available · object · required

Volume disponível para novos withdrawals.

Show child attributes

reserved · object · required

Volume reservado por withdrawals em andamento.

Show child attributes

used · object · required

Volume já utilizado por withdrawals.

Show child attributes

expiresAt · string<date-time> · required

Validade do lote.

createdAt · string<date-time> · required

updatedAt · string<date-time> · required

externalId · string | null

referenceRate · string

BRL por USD, até 8 casas decimais.

Pattern: ^[0-9]+(\.[0-9]{1,8})?$

Example:

"5.43210000"

spread · object

Spread de câmbio: única tarifa da remessa.

Show child attributes

pendingSettlement · object | null

Obrigação em USDC referente ao volume não utilizado. null até a apuração, cujo evento será comunicado antes da disponibilidade geral.

Show child attributes

settlementId · string | null

Lote de liquidação da obrigação, quando existir.

metadata · object