Stablecoin wallet API and infrastructure: how to add stablecoin wallets to your app
What a stablecoin wallet API does, the four kinds of providers, the call-by-call flow, the ledger and the US and EU rules, from a team that shipped USD and stablecoin wallets with debit cards.
A stablecoin wallet API lets your app create a wallet per customer, move dollars in and out of a stablecoin and read balances while a regulated provider holds the funds. The fastest route is that provider’s hosted KYC and custodial wallets, one transfer type, cards second, and your own ledger mirroring every provider event.
Listen to the summary ·
Read the transcript
On Freedom Pro, a platform we built, members earn on their team’s activity. The earnings land in a USD or stablecoin wallet, and a debit card spends them. Nobody in that flow has to know what a blockchain is.
The fastest way to add stablecoin wallets is to let a regulated orchestration provider hold the funds and run the regulated steps. Use its hosted identity checks and custodial wallets, launch one transfer type, and add cards second.
Build your own ledger that mirrors every provider event. Let webhooks confirm each state, and reconcile against the provider daily. For retries, Bridge requires an idempotency key on every POST request.
Check two rule sets before launch. In the US, the GENIUS Act takes effect on January 18, 2027, or 120 days after final regulations if that comes first. As of October 18, 2026, no final rule had been published. Issuers may not pay holders interest or yield, so run any rewards idea past counsel. In the EU, the coin itself has to fit MiCA. Circle says USDC and EURC are issued in the EU in compliance with it.
Stablecoins are the wrong rail when users need what a bank account gives them, such as deposit insurance, checks and ATMs. The guide below walks through the integration call by call.
AI-generated voice summary of this guide.
A stablecoin wallet API lets your app open a wallet for each customer, move dollars in and out of a dollar stablecoin, and show balances, while a regulated provider holds the funds and runs the regulated steps. Your app owns the screens, the ledger and the support tools.
That is how Freedom Pro works. A member signs up, picks the services they already pay for, and earns on their team’s activity. The earnings land in a USD or stablecoin wallet, and a debit card spends them. Nobody in that flow has to know what a blockchain is. Behind it sit a stablecoin provider’s API, a ledger we built, and a lot of decisions about who holds the money. This guide takes those decisions in the order a product team meets them.
The fastest way to add stablecoin wallets to an existing app
The fastest way is to let a regulated orchestration provider hold the funds and run the regulated steps, while your app owns onboarding screens, the ledger and the interface. You integrate through its API instead of holding crypto yourself.
A first release that ships quickly usually looks like this:
- Hosted identity checks. Use the provider’s hosted KYC flow at first. Building your own document capture can wait.
- Custodial wallets. The provider creates and holds a wallet per customer. You never touch private keys.
- One transfer type. For example, bank dollars in through a virtual account and converted to a dollar stablecoin. Add withdrawals and wallet-to-wallet sends after the first one is reconciled daily without surprises.
- Cards second. A card program adds lifecycle states, disputes and spend controls. Launch it once balances are trusted.
Bridge’s documentation shows how much of this one provider can cover: virtual accounts that accept USD, EUR, GBP, MXN and more, each with a unique account and routing number; orchestration APIs for on-ramps, off-ramps and crypto-to-crypto transfers; custodial wallets; cards backed by stablecoins; and issuance of your own stablecoin.
What a stablecoin wallet API does
A stablecoin wallet API is a set of calls and webhooks for five jobs: create a customer, verify them, open a wallet, move money, and report every change of state back to you. Reading balances and history is the easy part; moving money safely is where integrations differ.
| Job | Typical calls | What your app keeps |
|---|---|---|
| Customers | Create customer, attach identity data | Your user ID beside the provider’s customer ID |
| Identity checks | Start hosted or API KYC, receive the result by webhook | Status and limits per customer |
| Wallets and accounts | Create wallet, create virtual bank account, list balances | Wallet and account IDs, chain and coin per wallet |
| Transfers | Deposit, convert, withdraw, send, with an idempotency key | A pending ledger entry per request |
| Events | Webhooks for every state change | An append-only ledger entry per event |
The five jobs of a stablecoin wallet API
- Typical calls
- Create customer, attach identity data
- What your app keeps
- Your user ID beside the provider’s customer ID
- Typical calls
- Start hosted or API KYC, receive the result by webhook
- What your app keeps
- Status and limits per customer
- Typical calls
- Create wallet, create virtual bank account, list balances
- What your app keeps
- Wallet and account IDs, chain and coin per wallet
- Typical calls
- Deposit, convert, withdraw, send, with an idempotency key
- What your app keeps
- A pending ledger entry per request
- Typical calls
- Webhooks for every state change
- What your app keeps
- An append-only ledger entry per event
Under the calls, the provider decides two things you can’t easily change later: who holds the keys, and whether each customer gets their own on-chain wallet. Circle’s wallet products show both choices. Its developer-controlled wallets “sign transactions and custody funds for internal operations or on behalf of end users”, and its user-controlled wallets let end users “sign transactions directly and maintain control over their funds”. Either type can be a plain externally owned account (EOA) or a smart contract account, which allows features such as sponsored network fees.
Stablecoin wallet providers: four kinds of infrastructure
Stablecoin infrastructure comes in four broad kinds, and the kind you pick decides who holds keys, how much you build and how much regulatory weight lands on you. Vendor lists mix them together, so separate them before you compare prices. The examples below come from Stripe’s stablecoin docs, Bridge’s and Circle’s; we name them to show the kinds, not to rank them, and we have shipped on Bridge.
| Kind | Who holds keys and funds | What you build | Regulatory weight on you | Example in vendor docs |
|---|---|---|---|---|
| Custodial orchestration | The provider, in custodial wallets per customer | Onboarding UI, ledger, transfer screens, support tools | Lower: the provider runs custody and the regulated flows | Bridge: virtual accounts, orchestration APIs, custodial wallets |
| Embedded user wallets | The user or your app, depending on how the wallet is set up | Wallet UX, recovery, transaction signing, on- and off-ramps | Depends on whether you ever control user funds | Privy, listed in Stripe’s docs to “create and manage crypto and stablecoin wallets for users, businesses, and agents”; Circle’s developer- and user-controlled wallets |
| Platform balances and cards | The platform provider, on your business account | Treasury flows, payouts, card controls | Lower, but tied to that provider’s program rules | Stripe: stablecoin balances, payouts to third parties in more than 160 countries, stablecoin-backed cards |
| Issuance | You, as the brand behind a coin, through an issuer partner | Treasury, mint and burn operations, distribution | Highest: issuer rules apply | Bridge issuance API to “issue your own stablecoin” |
Stablecoin wallet infrastructure by kind (examples from each vendor’s own docs, checked November 3, 2026)
- Who holds keys and funds
- The provider, in custodial wallets per customer
- What you build
- Onboarding UI, ledger, transfer screens, support tools
- Regulatory weight on you
- Lower: the provider runs custody and the regulated flows
- Example in vendor docs
- Bridge: virtual accounts, orchestration APIs, custodial wallets
- Who holds keys and funds
- The user or your app, depending on how the wallet is set up
- What you build
- Wallet UX, recovery, transaction signing, on- and off-ramps
- Regulatory weight on you
- Depends on whether you ever control user funds
- Example in vendor docs
- Privy, listed in Stripe’s docs to “create and manage crypto and stablecoin wallets for users, businesses, and agents”; Circle’s developer- and user-controlled wallets
- Who holds keys and funds
- The platform provider, on your business account
- What you build
- Treasury flows, payouts, card controls
- Regulatory weight on you
- Lower, but tied to that provider’s program rules
- Example in vendor docs
- Stripe: stablecoin balances, payouts to third parties in more than 160 countries, stablecoin-backed cards
- Who holds keys and funds
- You, as the brand behind a coin, through an issuer partner
- What you build
- Treasury, mint and burn operations, distribution
- Regulatory weight on you
- Highest: issuer rules apply
- Example in vendor docs
- Bridge issuance API to “issue your own stablecoin”
Most fintech and platform products start in the first row. Embedded wallets fit crypto-native users, or teams that want to own more of the stack. Issuance is a business decision about becoming a stablecoin brand, not a wallet feature, and under the GENIUS Act it brings issuer-level rules.
Custodial or non-custodial: who holds the keys decides your obligations
Whoever can move the funds carries the obligations, so decide custody before you design screens. In a custodial model the provider holds the keys; in a non-custodial model the user does, and your app helps them sign.
The OCC’s final GENIUS Act rule shows how regulators think about it. As summarized by WilmerHale, the rule’s exclusion for companies that provide wallet hardware or software now applies only where the company “neither controls nor holds itself out as controlling” the customer’s assets. That is a useful test for your own design: if your servers can move a user’s balance without them, or your marketing implies you hold the money, assume you are in a custody conversation, and take it to counsel.
For consumer products, custodial wallets with a regulated provider are the practical default. Users get password resets and support. You get a partner that runs sanctions screening and can freeze an account when asked.
A second choice sits inside custodial: omnibus or segregated. In an omnibus setup many customers’ funds share one provider wallet and your ledger is the only record of who owns what. With segregated wallets each customer has their own, so the provider’s records already split balances by customer, which makes reconciliation, support and audits simpler. Omnibus puts all of that weight on your ledger. Ask which model a provider uses before you design the ledger.
- The provider holds the keys
- Users get password resets and support
- The provider runs sanctions screening and can freeze an account
- The user holds the keys
- Your app helps them sign
- Suits users who want to hold their own keys
How a stablecoin wallet integration works, step by step
An integration is a sequence of provider objects and events that your ledger mirrors one for one. The exact names vary by provider; the shape is the same:
- Create the customer in the provider with your own user ID stored beside the provider’s ID.
- Run identity checks, hosted or through the API, and listen for the result by webhook.
- Open the money objects: a wallet, a virtual account for bank deposits, or both.
- Move money with a transfer request: deposit, conversion, withdrawal or send.
- Receive webhooks for every state change and write each one to your ledger.
- Reconcile your balances against the provider’s records on a schedule.
- Issue a card on the balance, once the steps above run cleanly.


Each object moves through states, and each state needs its own screen copy. These are the ones a first release has to handle:
| Object | State | What the user sees | What your system does |
|---|---|---|---|
| Customer | Approved | Full access | Open wallet and virtual account |
| Customer | Pending review | “We’re checking your details”, with a time estimate | Block money movement, poll or wait for webhook |
| Customer | Rejected | A plain reason and a support route | No wallet; keep the record for audit |
| Customer | Limited | Which limit applies | Enforce the limit server-side on every request |
| Transfer | Pending | Amount, destination, “in progress” | Reserve the amount in your ledger |
| Transfer | Completed | Receipt with reference | Post the final entry, release the reserve |
| Transfer | Failed or returned | What happened and what to do next | Reverse with a new ledger entry, never an edit |
States a stablecoin wallet app must handle
- State
- Approved
- What the user sees
- Full access
- What your system does
- Open wallet and virtual account
- State
- Pending review
- What the user sees
- “We’re checking your details”, with a time estimate
- What your system does
- Block money movement, poll or wait for webhook
- State
- Rejected
- What the user sees
- A plain reason and a support route
- What your system does
- No wallet; keep the record for audit
- State
- Limited
- What the user sees
- Which limit applies
- What your system does
- Enforce the limit server-side on every request
- State
- Pending
- What the user sees
- Amount, destination, “in progress”
- What your system does
- Reserve the amount in your ledger
- State
- Completed
- What the user sees
- Receipt with reference
- What your system does
- Post the final entry, release the reserve
- State
- Failed or returned
- What the user sees
- What happened and what to do next
- What your system does
- Reverse with a new ledger entry, never an edit
For retries, Bridge’s API reference requires an Idempotency-Key header on every POST request and says not to send one with GET, PUT, PATCH or DELETE. The key holds for 24 hours after the first request, a retry must send the identical request body, and reusing the key after the 24 hours returns a 422 error.
Ledger rules that prevent wrong balances
Most bugs in wallet products are ledger bugs, not interface bugs. Your ledger is the record your support team, your finance team and your users read, and the provider’s records are what it must match.
- Store both IDs. Every customer, wallet, destination and transfer carries your ID and the provider’s ID side by side, so support can search either.
- Append, never edit. A reversal or a fee is a new entry linked to the original one.
- Let webhooks drive state. Your app requests; the provider’s events confirm. A screen never shows “completed” on the strength of an API response alone.
- Replay safely. Webhooks arrive twice and out of order. Process them by event ID, idempotently.
- Reconcile daily, alert on any difference. A wallet that shows “pending” honestly loses less trust than one that shows a wrong balance for a few minutes.
What the GENIUS Act final rule means for a product team
The GENIUS Act is the US federal law for payment stablecoins, and it takes effect on January 18, 2027. It was signed on July 18, 2025, and the OCC issued its final implementing rule on October 21, 2026 (OCC Bulletin 2026-50), effective the same day as the Act.
- Jul 18, 2025Signed into law
- Feb 25, 2026OCC proposes its rulesNew 12 CFR Part 15.
- Jul 18, 2026Statutory deadline passesNo final rules yet.
- Oct 21, 2026OCC final rule issuedBulletin 2026-50.
- Jan 18, 2027Takes effectThe Act and the OCC rule, with no transition period.
The OCC rule covers national banks, federal savings associations, federal branches, foreign issuers and nonbank issuers under OCC supervision. What changed from the proposal, as summarized by WilmerHale on October 27, 2026:
- Yield. The ban on issuers paying holders interest or yield stays, now worded as in the Act. The OCC dropped the proposed presumption that certain arrangements violate it, and keeps anti-evasion authority through application review and supervision.
- Redemption. Issuers keep a two-business-day limit. The proposal’s automatic extension when requests pass 10% of outstanding value in 24 hours is gone; the issuer notifies the OCC and may ask for one.
- Custody. Wallet hardware and software providers are excluded only if they neither control nor hold themselves out as controlling customer assets, and covered custodians must record customer assets separately.
Three product decisions follow. Pick coins and providers that will operate as permitted issuers or work with them, and ask what their plan is for January 18, 2027. Run every “rewards on your balance” idea past counsel before design: the presumption is gone, the ban and the OCC’s anti-evasion powers are not. And keep identity and sanctions checks strict, because for your provider they are a legal obligation. Other agencies’ rules, including AML standards and rules for state issuers, follow their own schedules; check them with counsel before launch.
Serving EU users: MiCA and which stablecoin you offer
In the EU the coin itself has to fit MiCA, so the stablecoin you offer may differ by market. MiCA treats dollar and euro stablecoins as e-money tokens, and on January 17, 2025 ESMA and the European Commission said national regulators should make sure crypto-asset service providers stop offering non-compliant tokens as soon as possible, and no later than the end of the first quarter of 2025.
Circle says it holds an e-money institution license from France’s ACPR and that USDC and EURC are issued in the EU in compliance with MiCA (Circle press release, July 1, 2024). For an EU launch that usually means three checks:
- A coin whose issuer is authorized under MiCA, such as USDC or EURC, confirmed with the provider on the day you launch.
- A provider or partner licensed to serve EU users, not only US ones.
- Screens and disclosures reviewed for each market you open.
We haven’t shipped an EU stablecoin product yet, so read this section as guidance from the public sources above, not as experience, and not as legal advice.
Questions to ask a stablecoin wallet provider
Ask how the provider behaves when something goes wrong, not only which coins and chains it supports. Each question below maps to a failure we design the ledger around; the right-hand column shows what one provider documents, so you know what a clear answer looks like.
| Ask | Failure it prevents | What a clear answer looks like |
|---|---|---|
| Who holds the keys and the funds, and under which license? | Your app ends up in a custody or money transmission role by accident | Bridge: custodial wallets held by Bridge |
| Omnibus or one wallet per customer? | Balances you can’t prove per customer | A named model, and how its records split balances |
| How do retries work? | A timeout and a retry pay twice | Bridge: an Idempotency-Key header on every POST, honored for 24 hours, identical body required |
| Which events arrive by webhook, and can they repeat? | A screen says “completed” before the money moved | A full event list per object, with event IDs you can deduplicate |
| How do we reconcile? | Balances drift for days before anyone notices | A list or report of transfers you can match to your ledger daily |
| Which rails in and out? | Users can deposit but not withdraw where they live | Bridge: virtual accounts in USD, EUR, GBP, MXN and more, plus on- and off-ramps |
| Which coins in which markets? | An EU launch with a coin that isn’t MiCA-compliant | A per-market coin list, confirmed on launch day |
| What is the GENIUS Act plan? | A coin or partner that can’t operate after January 18, 2027 | The issuer’s licensing path, in writing |
| Cards on the same balance? | A second integration and a second ledger later | Bridge: cards backed by stablecoin balances |
Provider questions and the failure each one prevents (Bridge column from its API docs, checked November 3, 2026)
- Failure it prevents
- Your app ends up in a custody or money transmission role by accident
- What a clear answer looks like
- Bridge: custodial wallets held by Bridge
- Failure it prevents
- Balances you can’t prove per customer
- What a clear answer looks like
- A named model, and how its records split balances
- Failure it prevents
- A timeout and a retry pay twice
- What a clear answer looks like
- Bridge: an Idempotency-Key header on every POST, honored for 24 hours, identical body required
- Failure it prevents
- A screen says “completed” before the money moved
- What a clear answer looks like
- A full event list per object, with event IDs you can deduplicate
- Failure it prevents
- Balances drift for days before anyone notices
- What a clear answer looks like
- A list or report of transfers you can match to your ledger daily
- Failure it prevents
- Users can deposit but not withdraw where they live
- What a clear answer looks like
- Bridge: virtual accounts in USD, EUR, GBP, MXN and more, plus on- and off-ramps
- Failure it prevents
- An EU launch with a coin that isn’t MiCA-compliant
- What a clear answer looks like
- A per-market coin list, confirmed on launch day
- Failure it prevents
- A coin or partner that can’t operate after January 18, 2027
- What a clear answer looks like
- The issuer’s licensing path, in writing
- Failure it prevents
- A second integration and a second ledger later
- What a clear answer looks like
- Bridge: cards backed by stablecoin balances
Fees matter too, but they come on top and change with volume; compare them once the answers above have narrowed the list.
Design for people who don’t care about crypto
Most users want dollars that move fast, so show balances in USD, hide chain details by default, and make the card the hero.
Use words like “balance”, “send” and “card” in the main flows, not “wallet address” or “network”. Advanced users can still find the chain, the transaction hash and the destination on a detail screen. Confirm every outgoing transfer with the amount and destination in plain words, because a stablecoin sent to the wrong address is hard to get back. Receipts matter more as money moves faster.
Stablecoin use cases that fit a fintech app, and when they don’t
Stablecoin wallets fit when money crosses borders, settles outside banking hours, or lands as platform earnings that users want to hold and spend in one place: payouts to contractors, creators and partner networks, cross-border transfers, and card spending from a dollar balance. Stablecoins are the wrong rail when your users need what a bank account gives them: deposit insurance through a partner bank, checks, cash deposits and ATMs. In that case a partner bank and a card program fit better.
Switch, a shared banking app we built for clubs and teams, made exactly that choice: Thread Bank as its FDIC-insured partner bank and Visa debit cards, with no stablecoins. Freedom Pro made the other one, because its members are paid as platform earnings and spend them by card.
What adding stablecoin wallets does to timeline and budget
A focused wallet integration fits inside one of our fixed-price builds of $25k–$120k, delivered in 6–16 weeks after discovery; what moves it up the band is how many money paths it has. These are the usual drivers, in our judgment:
- Transfer types. Each one (deposit, conversion, withdrawal, send, payout) adds states, webhooks, failure screens and reconciliation rules.
- Cards. Card lifecycle, limits, disputes and wallet provisioning add a second integration.
- Markets. US plus EU means two coin and partner checks and two sets of disclosures.
- Your own onboarding UI instead of the provider’s hosted flow.
- Operations tooling. Search by provider ID, holds, case notes and exports for support and compliance.
Provider fees, KYC checks and card program costs come on top and are usage-based. For full scopes of two fintech products and their line items, see our guide to fintech app development cost; our pricing page lists the Discovery Sprint and build terms.
Launch checklist for stablecoin wallets
Before real money moves, check each of these:
- Money flows drawn end to end, with counsel’s sign-off on who holds funds at each step.
- Sandbox tests for every transfer type, including failures, returns and late webhooks.
- One idempotency key per user intent, stored with the transfer and reused inside the provider’s window.
- Webhook replay test: the same events delivered twice and out of order leave balances unchanged.
- Daily reconciliation with alerts, and a support view that searches by provider ID.
- Onboarding tested for approved, pending-review, rejected and limited customers.
- Coin and provider confirmed for every market you launch in, and the provider’s GENIUS Act plan on file for US users.
- Copy reviewed for anything that implies deposit insurance, interest or yield on a stablecoin balance.
- Limits for new accounts and a fast way to freeze one when the provider asks.
How Freedom Pro uses it
On Freedom Pro, stablecoin wallets are where a partner network gets paid. Partners earn on their team’s activity in the back office, and earnings arrive in USD or stablecoin (USDC) balances that members spend by debit card, under the same single sign-on as the platform’s wireless, streaming and wellness services. Bridge provides the wallets and the card program; we built the product around it, from the member portal to the back office. That makes Freedom Pro a bundled financial services platform as much as a direct-selling one, and the commission side is covered in our guide to MLM software and commission engines.
If you are adding wallets or cards to an existing product, our fintech app development team starts with the provider choice and the money flows, then builds the ledger and the apps.
Sources
- Bridge API documentation, Bridge
- Idempotence, Bridge API reference
- Wallets, Circle
- GENIUS Act Regulations: Final Rule (Bulletin 2026-50), OCC
- OCC Finalizes GENIUS Act Rule for Permitted Payment Stablecoin Issuers, WilmerHale
- ESMA and European Commission publish guidance on non-MiCA compliant ARTs and EMTs, ESMA
Mobile App Development
Native and cross-platform iOS and Android apps, from fintech and streaming to connected hardware, designed, built and launched to the stores.





