When you want the conversion to be a decision, not a default
Automatic conversion is the right tool when you want every payment to settle into a reference asset with no thought. But not every treasury wants that. Some teams hold what arrives and convert deliberately — because they batch month-end consolidation, because they want to choose the moment, or because the asset they keep depends on what is happening that week rather than a setting fixed in advance.
Manual conversion serves that posture. Instead of a conversion firing on credit, balances sit in your account in the assets the customers paid with, and you convert on demand. The trigger is a decision your team makes, not a rule the platform applies automatically. That keeps the move visible and intentional: a named source asset, a named target, and an amount you picked, executed at a time you chose.
The two modes are not exclusive. Most teams that use balance conversion run automatic on the bulk of steady revenue and reach for manual conversion for the periodic, judgment-based moves — the explicit, on-demand conversion this page covers — where each move is a treasury call rather than a rule firing on every payment.
What a manual conversion is
A manual conversion is an explicit operation with three inputs: the source asset you are converting from, the target asset you are converting to, and the amount. You provide those, the platform converts the held value toward the target, and the result lands in your balance denominated in the target asset. Nothing happens to assets you did not name — only the source amount you specified moves.
Crucially, the conversion is a recorded event, not an opaque adjustment. It is written into your balance history with provenance the same way every other money movement on halfin is, so the change in your held balances has a cause your accounting system can trace. You are never left looking at a balance that shifted with no record of why. A conversion you triggered is a line you can point to.
Because the operation is bounded to the source amount you named, it is also safe to do in pieces. Converting part of a held asset now and the rest later is just two recorded conversions; there is no all-or-nothing sweep. That matters when you are consolidating gradually or only need enough of one asset to cover a specific obligation.
- You name the source asset, the target asset, and the amount — only that amount moves.
- The result is credited to your balance in the target asset.
- Every conversion is written to balance history with provenance, so the change is traceable.
- Partial conversions are fine — convert only what you need, when you need it.
Two ways to trigger it: dashboard or API
Manual conversion runs from the same two surfaces the rest of halfin does. In the dashboard, an operator picks the source and target assets and the amount and confirms the move — the right path for a finance person doing a deliberate, occasional consolidation without writing code. The conversion shows up in balance history immediately, attributed to the operator who ran it.
Programmatically, the conversion is part of the same spec-first REST API at api.thehalfin.com/api/v1 that you already use for invoices, payouts, and balances. That suits a treasury process you want to automate on your own schedule — a nightly consolidation job, or a step in a payout pipeline that tops up the network you are about to pay on. The request headers are only X-API-Key and Content-Type, and you authenticate with a scoped API key, the same as every other call.
Whichever surface you use, the outcome is identical: a recorded conversion against your balance. The dashboard is the human path; the API is the programmatic path. They are not two different products — they are two front doors to the same on-demand conversion.
What manual conversion is good for
The table below maps the common treasury situations to why a manual conversion fits them. Read it as a guide for when to reach for the on-demand move rather than leaving conversion automatic — the unifying thread is that each row is a decision someone made, at a moment that matters, rather than a rule running on every payment.
| Situation | Why manual | Result |
|---|---|---|
| Leftover assets accumulated over a period | You want to consolidate on your own schedule, not per-payment | Dust and odd assets folded into one reference asset, with a record |
| Upcoming payout run on a specific network | You need liquidity in a particular asset and network before the batch | Held value rebalanced toward the asset the payouts will draw from |
| Treasury policy call made off-platform | The decision is yours; the platform should just execute it | A deliberate, auditable conversion event you can point to |
| Asset that had no conversion route on receipt | It was credited as-is; you decide what to do with it later | Converted on demand once you choose a target it has a route to |
Funding a payout run on the right network
The most operational use of manual conversion is staging liquidity before a payout. The same logical asset lives on several networks — USDT as TRC-20, ERC-20, or Solana SPL; USDC as ERC-20, Solana SPL, or on Base — and a payout draws from a specific one of those balances. If a single or mass payout run is going out over TRC-20 but most of your stablecoin accumulated as ERC-20, the batch can come up short on the network it actually pays on.
Manual conversion is how you fix that before the run rather than during it. You convert held value toward the asset and network the upcoming batch needs, confirm the target balance covers the obligation, and only then release the payout. Because payouts enter pending-approval and are released from the dashboard, you have a natural checkpoint to confirm the liquidity is positioned before anything goes out. The conversion and the payout are separate recorded events, so reconciliation stays clean on both sides.
Convert, then read the result back
A manual conversion changes your held balances, and your balances are the source of truth for what you hold. After a conversion settles, you read the updated balances through the same REST endpoint you already use for everything else — there is no parallel conversion ledger to stitch together. The snippet below reads current balances so a treasury job can confirm the target asset now covers what it was converting for.
Treat the conversion as a change to these balances rather than as its own bookkeeping system. The conversion event records why the numbers moved; the balances record where they landed. Keep the API balance as the single figure your accounting reconciles against, and let manual conversion be the deliberate lever that shapes it.
# Read current merchant balances after a manual conversion has settled
curl https://api.thehalfin.com/api/v1/balances \
-H "X-API-Key: $HALFIN_API_KEY"
# Each entry reports the asset, network, and amount you currently hold.
# Confirm the target asset now covers the obligation you converted for
# (for example, the network your next payout run draws from).
# Amounts are JSON strings — never parse them as floating-point numbers.What manual conversion does not do
Manual conversion moves value between crypto assets you already hold on the platform. It is not a fiat off-ramp: it does not turn your held crypto into bank-settled fiat, and halfin does not sell crypto to your customers. Converting "to USD" here means converting into a USD-denominated stablecoin such as USDC or USDT, not into a fiat bank balance.
A conversion also needs a supported route between the two assets you name. Routes cover the assets and networks halfin supports for settlement; where no route exists between a source and your chosen target, the source asset stays held and you pick a different target or hold it as-is. The platform makes the supported moves clean and recorded — it does not promise a path between every possible pair.
And manual conversion is a treasury operation, not a custody guarantee. The controls around it are the same ones that apply everywhere on halfin — scoped API keys, operator permissions, and a full audit trail of every recorded move — and nothing beyond signing, permissions, and that audit trail should be read into it.