USDC Inventory

The mode must be enabled for your account; otherwise the API returns FUNDING_MODE_NOT_ENABLED.

1. Quote with usage = INVENTORY

Request the quote in POST /v1/fx/quotes with usage = INVENTORY and exactly one of sourceAmount (USD) or destinationAmount (BRL). The response has two dates: expiresAt is the validity of the quote itself; inventoryExpiresAt is the validity the lot will have if you create it.

POST /v1/fx/quotes · request

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

Request body

{
  "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. Create the lot

Call POST /v1/inventories with the quoteId. This call is the acceptance: in one operation LB Pay closes rate and volume with you, creates the USDC payment promise and creates the lot, which starts ACTIVE. The quote becomes USED and records the inventoryId. Each call creates a new, independent lot; lots are never aggregated. A lot can exist without any withdrawal.

POST /v1/inventories · request

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

Request body

{
  "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. Check balances

GET /v1/inventories/{inventoryId} returns rate, validity and balances. Every balance is shown in BRL and USD. Control is in BRL; USD is calculated at the lot rate.

Field	Meaning
`total`	Contracted volume
`available`	Volume available for new withdrawals
`reserved`	Volume reserved by withdrawals in progress
`used`	Volume already used by withdrawals

total = available + reserved + used, always.

Example: a lot of USD 100,000.00 at 5.40000000 is BRL 540,000.00. A withdrawal of BRL 10,000.00 reserves USD 1,851.85 (10,000 ÷ 5.40).

Moment	available	reserved	used
Lot created	BRL 540,000.00 · USD 100,000.00	0	0
Withdrawal reserved	BRL 530,000.00 · USD 98,148.15	BRL 10,000.00 · USD 1,851.85	0
Volume used	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

Lot status

Status	Meaning
`ACTIVE`	Within validity, with available volume.
`DEPLETED`	No available volume (all reserved or used). Returns to `ACTIVE` if a reservation is released within validity.
`EXPIRED`	Past `expiresAt`. Does not accept new withdrawals.

4. Create the withdrawal

Create the withdrawal with funding.mode = INVENTORY, funding.inventoryId, destinationAmount (the BRL the beneficiary receives) and senderQuote. Do not send quoteId. Amounts and rate come from the lot. LB Pay checks that the lot exists in your account, is within validity and has enough available BRL, applies the usual withdrawal checks and reserves the volume atomically. Another lot is never used automatically.

Field	PREFUNDED / CREDIT	INVENTORY
`quoteId`	Required	Not accepted
`funding.inventoryId`	Not accepted	Required
`destinationAmount` (BRL)	Not accepted	Required
`senderQuote`	Optional	Required

A violation returns VALIDATION_ERROR (400), with the field in details.

senderQuote holds the data of the FX operation between the MSB and the sender: rate, USD and BRL amounts, quote time and your reference. It is recorded as received and used to formalize the operation. It does not change the remittance amounts or the lot rate. Its structure may receive new fields.

POST /v1/remittances/withdrawals · request

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

Request body

{
  "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. Track and reconcile

inventory.created: lot created. inventory.status_changed: ACTIVE ↔ DEPLETED, or EXPIRED. In both, data.object is the Inventory.
Remittances funded by a lot follow the remittance.* events.
Balance changes without a status change do not send an event. Check the balance in GET /v1/inventories/{inventoryId}.
List the remittances of a lot with GET /v1/remittances?inventoryId=.
In an INVENTORY remittance, quoteId is null, inventoryId identifies the lot and fx.rate is the lot rate. fx.status = CONTRACTED only after the execution is confirmed. In REJECTED, the reserved volume returns to the lot.

Errors

Code	HTTP	Cause	What you do
`QUOTE_USAGE_MISMATCH`	422	Quote used in the wrong operation: `INVENTORY` in a withdrawal, or `REMITTANCE` in `POST /v1/inventories`.	Request a new quote with the right `usage`.
`DUPLICATE_INVENTORY_EXTERNAL_ID`	409	`externalId` already used by another lot in your account.	Use a new `externalId`, or find the existing lot with `GET /v1/inventories?externalId=`.
`INVENTORY_NOT_FOUND`	422	The lot in `funding.inventoryId` does not exist in your account.	Check the `inventoryId`. A lot from another account returns the same error.
`INVENTORY_EXPIRED`	422	The lot is `EXPIRED`.	Use another `ACTIVE` lot or contract a new one.
`INSUFFICIENT_INVENTORY_BALANCE`	422	Available volume in the lot is lower than `destinationAmount`.	Check the balance in `GET /v1/inventories/{inventoryId}` before retrying. Another lot is never used automatically.
`FUNDING_MODE_NOT_ENABLED`	422	`INVENTORY` is not enabled for your account. Applies to lot creation and to the withdrawal.	Contact LB Pay to enable the mode.

Good practices

Always inform the lot explicitly. LB Pay never uses another lot automatically.
Handle INSUFFICIENT_INVENTORY_BALANCE by checking the balance before trying again.
Send an Idempotency-Key when creating the lot and the withdrawal.
Send in senderQuote the real values of the operation with the sender.

In definition

Validity and expiration of unused volume, lot cancellation and collection of the USDC obligation are still being defined. These rules will be communicated before general availability.

Get started

Remittances

Records and balances

Operations

1. Quote with usage = INVENTORY

2. Create the lot

3. Check balances

Lot status

4. Create the withdrawal

5. Track and reconcile

Errors

In definition

​1. Quote with usage = INVENTORY

​2. Create the lot

​3. Check balances

​Lot status

​4. Create the withdrawal

​5. Track and reconcile

​Errors

​In definition

1. Quote with usage = INVENTORY

2. Create the lot

3. Check balances

Lot status

4. Create the withdrawal

5. Track and reconcile

Errors

In definition