Stablecoin API objects explained: customers, bank accounts, wallets, quotes, payouts, and webhooks

A stablecoin API is built from about eight objects. A customer is the verified person or business. Bank accounts and wallets are where money goes or sits. A quote locks the rate and fees. A payout or payin executes that quote, a virtual account collects repeat deposits, and webhook events report every change. Get those relationships right and the integration code stays small.

Key takeaways

• The customer is a verified legal party, not your login user. Model it that way from day one.
• A quote is single use and lives for minutes. A payout or payin is the durable record you reconcile.
• Store the provider's IDs, your idempotency key, and the rail reference on every payment, with amounts as integers in minor units.
• Webhooks are delivered at least once and can arrive out of order. Your state machine should only move forward.
• Names vary by provider (receiver, beneficiary, counterparty), but the roles below show up in nearly every type of stablecoin API.

The integration guide walks through the calls in order. This page covers the layer under the calls: what each object means, how they link, and what your own database should keep.

What are the core objects in a stablecoin API?

The core objects are the environment, customer, bank account, wallet, quote, payout, payin, virtual account, and webhook event.

Less common objects follow the same pattern: transfers between wallets, bills to pay (payables), off-ramp wallets that pay out on deposit, and partner fees. If you understand the ten above, you can read any of them.

How do the objects relate to each other?

Every object hangs off a customer inside one environment, and every money movement points back to a quote.

Picture a tree. The instance is the root. Customers sit under it. Each customer owns its destinations and sources: many bank accounts, many wallets, and usually one or a few virtual accounts. A virtual account points at the wallet where converted stablecoins land.

Money movements sit beside the tree, not inside it. A payout quote references a customer's bank account plus the network and token that fund it. The payout references that quote and the wallet the stablecoins come from. A payin references its payin quote and the destination wallet. Webhook events reference whichever object changed.

Three cardinality rules save the most bugs:

• One quote backs one payout. A second payout with the same quote ID should be rejected.
• A bank account belongs to the paying customer, not the payee. A customer named John can pay a bank account held by Jack.
• Funds sit in exactly one place at a time. An external wallet is under the customer's control, a managed wallet is held by the provider, and a payout in flight is in the provider's hands until it completes or returns. Payout statuses shows each step.

Which IDs should you store in your own database?

Store every provider ID next to the record it maps to, plus the references your finance team will ask for later.

Amounts deserve their own rule. Store integers in minor units, the way the API sends them. A request_amount of 66600 in USD means $666.00. A float will eventually round a cent the wrong way, and finance will find it at month end.

What does a quote and payout request look like?

A quote request names the destination, amount, and funding token; the payout request names the quote. The example below is generic and illustrative. Field names differ by provider.

Three details in that exchange matter. expires_at is a timestamp you read, not a window you assume. The Idempotency-Key header, described in an IETF draft, lets you retry the POST without paying twice; our idempotency guide covers the edge cases. And the payout comes back as processing, not completed. The final answer arrives by webhook.

Which states does each object move through?

Each object has a small state machine, and your code should mirror it rather than invent its own.

Model "on hold" as pending, not as an error. SWIFT and USD payouts often pass through a review hold as a standard step, so most users will see it at least once.

How should you build the data model, step by step?

Build it in the same order money moves. Seven steps:

1. Create one environment per stage. Keep sandbox and production IDs in separate databases or clearly tagged columns. An ID from one never works in the other.
2. Map your users to customers. One customer per legal party that sends or receives money. A company with five admins is one business customer, not five.
3. Attach destinations to the customer. Bank accounts and wallets get their own tables with a foreign key to the customer.
4. Write the payment row before you call the API. Generate the idempotency key, store it with status created, then request the quote and the payout.
5. Record every provider ID as it comes back. Quote ID, then payout ID, then the transaction hash and rail reference.
6. Apply webhooks through a forward-only state machine. Deduplicate by message ID. The Standard Webhooks spec recommends using the message ID as an idempotency key for this.
7. Reconcile on a schedule. Fetch anything still open past its expected arrival and compare it with your ledger. The webhooks and reconciliation guide has the matching logic.

What are the 8 most common data-model mistakes?

These eight show up in nearly every first integration, and each has a one-line fix.

Where does BlindPay fit?

BlindPay's API uses these same objects with prefixed IDs, so a log line tells you what you are looking at. The docs come in two flavors: Abstracted, for teams that think in bank rails (virtual accounts, payins, payouts), and Advanced, for teams that work with wallets, approvals, and chains directly. Both describe the same API. Official SDKs for Node.js, Python, Go, PHP, and Swift are generated from one OpenAPI 3.1 spec, so the object shapes match across languages. The customers reference and the webhook event list are good first reads.

What to do next

Draw your current schema next to the table in this article. For each payment row, check that you store the quote ID, the payout or payin ID, your idempotency key, and the amount in minor units. If any of those is missing, add the column before your first production payout, not after the first reconciliation break.