USDC Inventory

A modalidade precisa estar habilitada para a sua conta; caso contrário, a API retorna FUNDING_MODE_NOT_ENABLED.

1. Cotar com usage = INVENTORY

Solicite a cotação em POST /v1/fx/quotes com usage = INVENTORY e exatamente um entre sourceAmount (USD) e destinationAmount (BRL). A resposta traz duas datas: expiresAt é a validade da própria cotação; inventoryExpiresAt é a validade que o lote terá se for criado.

POST /v1/fx/quotes · requisição

POST /v1/fx/quotes
Idempotency-Key: 7f1c2a9e-inv-quote

Corpo da requisição

{
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "sourceAmount": "100000.00",
  "usage": "INVENTORY"
}

201 · FxQuote

{
  "quoteId": "qt_01JA1X",
  "status": "AVAILABLE",
  "usage": "INVENTORY",
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "source": {
    "currency": "USD",
    "amount": "100000.00"
  },
  "destination": {
    "currency": "BRL",
    "amount": "540000.00"
  },
  "referenceRate": "5.46558704",
  "rate": "5.40000000",
  "spread": {
    "percentage": "1.2",
    "amount": {
      "currency": "USD",
      "amount": "1200.00"
    }
  },
  "expiresAt": "2026-11-04T14:05:00Z",
  "inventoryExpiresAt": "2026-11-10T23:59:59Z",
  "inventoryId": null,
  "createdAt": "2026-11-04T14:00:00Z"
}

2. Criar o lote

Chame POST /v1/inventories com o quoteId. Essa chamada é o aceite: em uma operação a LB Pay fecha com você taxa e volume, cria a promessa de pagamento em USDC e cria o lote, que nasce ACTIVE. A cotação passa a USED e registra o inventoryId. Cada chamada cria um lote novo e independente; lotes nunca são agregados. O lote pode existir sem nenhum withdrawal.

POST /v1/inventories · requisição

POST /v1/inventories
Idempotency-Key: 7f1c2a9e-inv-create

Corpo da requisição

{
  "quoteId": "qt_01JA1X",
  "externalId": "inventory-2026-11-04-001"
}

201 · Inventory

{
  "inventoryId": "inv_01JA2B",
  "externalId": "inventory-2026-11-04-001",
  "quoteId": "qt_01JA1X",
  "status": "ACTIVE",
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "referenceRate": "5.46558704",
  "rate": "5.40000000",
  "spread": {
    "percentage": "1.2",
    "amount": {
      "currency": "USD",
      "amount": "1200.00"
    }
  },
  "total": {
    "source": { "currency": "USD", "amount": "100000.00" },
    "destination": { "currency": "BRL", "amount": "540000.00" }
  },
  "available": {
    "source": { "currency": "USD", "amount": "100000.00" },
    "destination": { "currency": "BRL", "amount": "540000.00" }
  },
  "reserved": {
    "source": { "currency": "USD", "amount": "0.00" },
    "destination": { "currency": "BRL", "amount": "0.00" }
  },
  "used": {
    "source": { "currency": "USD", "amount": "0.00" },
    "destination": { "currency": "BRL", "amount": "0.00" }
  },
  "pendingSettlement": null,
  "settlementId": null,
  "expiresAt": "2026-11-10T23:59:59Z",
  "createdAt": "2026-11-04T14:01:12Z",
  "updatedAt": "2026-11-04T14:01:12Z"
}

3. Consultar saldos

GET /v1/inventories/{inventoryId} retorna taxa, validade e saldos. Todos os saldos aparecem em BRL e USD. O controle é feito em BRL; o USD é calculado na taxa do lote.

Campo	Significado
`total`	Volume contratado
`available`	Volume disponível para novos withdrawals
`reserved`	Volume reservado por withdrawals em andamento
`used`	Volume já utilizado por withdrawals

total = available + reserved + used, sempre.

Exemplo: um lote de USD 100.000,00 à taxa 5,40000000 equivale a BRL 540.000,00. Um withdrawal de BRL 10.000,00 reserva USD 1.851,85 (10.000 ÷ 5,40).

Momento	available	reserved	used
Lote criado	BRL 540.000,00 · USD 100.000,00	0	0
Withdrawal reservado	BRL 530.000,00 · USD 98.148,15	BRL 10.000,00 · USD 1.851,85	0
Volume utilizado	BRL 530.000,00 · USD 98.148,15	0	BRL 10.000,00 · USD 1.851,85
Withdrawal `REJECTED`	BRL 540.000,00 · USD 100.000,00	0	0

Status do lote

Status	Significado
`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.

4. Criar o withdrawal

Crie o withdrawal com funding.mode = INVENTORY, funding.inventoryId, destinationAmount (o BRL que o beneficiário recebe) e senderQuote. Não envie quoteId. Valores e taxa vêm do lote. A LB Pay confere se o lote existe na sua conta, está dentro da validade e tem BRL disponível suficiente, aplica as validações usuais do withdrawal e reserva o volume de forma atômica. Outro lote nunca é usado automaticamente.

Campo	PREFUNDED / CREDIT	INVENTORY
`quoteId`	Obrigatório	Não aceito
`funding.inventoryId`	Não aceito	Obrigatório
`destinationAmount` (BRL)	Não aceito	Obrigatório
`senderQuote`	Opcional	Obrigatório

Violação retorna VALIDATION_ERROR (400), com o campo em details.

senderQuote traz os dados da operação de câmbio da MSB com o remetente: taxa, valores em USD e BRL, horário da cotação e a sua referência. É gravado como recebido e usado na formalização da operação. Não altera os valores da remessa nem a taxa do lote. A estrutura pode receber novos campos.

POST /v1/remittances/withdrawals · requisição

POST /v1/remittances/withdrawals
Idempotency-Key: 7f1c2a9e-wd-125

Corpo da requisição

{
  "senderId": "snd_789",
  "externalId": "remittance-125",
  "destinationAmount": "10000.00",
  "funding": {
    "mode": "INVENTORY",
    "inventoryId": "inv_01JA2B"
  },
  "beneficiaryId": "ben_125",
  "purpose": "FAMILY_MAINTENANCE",
  "senderRelationship": "FAMILY",
  "senderQuote": {
    "rate": "5.55000000",
    "source": {
      "currency": "USD",
      "amount": "1801.80"
    },
    "destination": {
      "currency": "BRL",
      "amount": "10000.00"
    },
    "quotedAt": "2026-11-04T14:00:00Z",
    "reference": "msb-quote-8812"
  }
}

201 · WithdrawalResponse

{
  "remittanceId": "rem_01JA3C",
  "type": "WITHDRAWAL",
  "quoteId": null,
  "inventoryId": "inv_01JA2B",
  "senderId": "snd_789",
  "externalId": "remittance-125",
  "status": "PROCESSING",
  "fundingMode": "INVENTORY",
  "message": "Remessa criada; câmbio e Pix ainda não confirmados."
}

422 · ApiError

{
  "code": "INSUFFICIENT_INVENTORY_BALANCE",
  "message": "Volume disponível no inventory inv_01JA2B é menor que destinationAmount.",
  "requestId": "req_9b1e",
  "retryable": false,
  "details": [
    {
      "field": "destinationAmount",
      "reason": "available BRL 4000.00"
    }
  ]
}

5. Acompanhar e conciliar

inventory.created: lote criado. inventory.status_changed: ACTIVE ↔ DEPLETED, ou EXPIRED. Nos dois, data.object é o Inventory.
Remessas financiadas por um lote seguem os eventos remittance.*.
Mudanças de saldo sem mudança de status não geram evento. Consulte o saldo em GET /v1/inventories/{inventoryId}.
Liste as remessas de um lote com GET /v1/remittances?inventoryId=.
Em uma remessa INVENTORY, quoteId é null, inventoryId identifica o lote e fx.rate é a taxa do lote. fx.status = CONTRACTED só depois da confirmação da execução. Em REJECTED, o volume reservado volta ao lote.

Erros

Código	HTTP	Causa	O que fazer
`QUOTE_USAGE_MISMATCH`	422	Cotação usada na operação errada: `INVENTORY` em withdrawal, ou `REMITTANCE` em `POST /v1/inventories`.	Solicite uma nova cotação com o `usage` correto.
`DUPLICATE_INVENTORY_EXTERNAL_ID`	409	`externalId` já usado por outro lote da sua conta.	Use um novo `externalId` ou localize o lote existente com `GET /v1/inventories?externalId=`.
`INVENTORY_NOT_FOUND`	422	O lote informado em `funding.inventoryId` não existe na sua conta.	Confira o `inventoryId`. Lote de outra conta retorna o mesmo erro.
`INVENTORY_EXPIRED`	422	O lote está `EXPIRED`.	Use outro lote `ACTIVE` ou contrate um novo.
`INSUFFICIENT_INVENTORY_BALANCE`	422	O volume disponível no lote é menor que `destinationAmount`.	Consulte o saldo em `GET /v1/inventories/{inventoryId}` antes de tentar de novo. Outro lote nunca é usado automaticamente.
`FUNDING_MODE_NOT_ENABLED`	422	`INVENTORY` não está habilitado para a sua conta. Vale para a criação do lote e para o withdrawal.	Fale com a LB Pay para habilitar a modalidade.

Boas práticas

Informe sempre o lote explicitamente. A LB Pay nunca usa outro lote automaticamente.
Trate INSUFFICIENT_INVENTORY_BALANCE consultando o saldo antes de tentar de novo.
Use Idempotency-Key na criação do lote e no withdrawal.
Envie em senderQuote os valores reais da operação com o remetente.

Em definição

Validade e expiração do volume não utilizado, cancelamento de lote e cobrança da obrigação em USDC ainda estão em definição. Essas regras serão comunicadas antes da disponibilidade geral.

Primeiros passos

Remessas

Cadastros e saldos

Operação

1. Cotar com usage = INVENTORY

2. Criar o lote

3. Consultar saldos

Status do lote

4. Criar o withdrawal

5. Acompanhar e conciliar

Erros

Em definição

​1. Cotar com usage = INVENTORY

​2. Criar o lote

​3. Consultar saldos

​Status do lote

​4. Criar o withdrawal

​5. Acompanhar e conciliar

​Erros

​Em definição

1. Cotar com usage = INVENTORY

2. Criar o lote

3. Consultar saldos

Status do lote

4. Criar o withdrawal

5. Acompanhar e conciliar

Erros

Em definição