Take your own margin

If you resell Conduit to your own customers, you can add your own margin to each movement you start. You declare it on the request; Conduit charges your customer, keeps the cash, and records a debt to you. Once a month that debt closes into a statement and Conduit pays it. You never handle the money. There is no separate account to reconcile, no fee to invoice, and nothing to sweep — for the flows on this page. A deposit works differently, because you don’t start it: see Charge a fee on a deposit.

Test this flow in sandbox. Margin is on by default there, so you can build against it before it’s enabled on live. Start with the sandbox quickstart, then conversion simulation, and the cheat sheet for every magic value and simulate endpoint.

Prerequisites

Margin enabled for your organization on live. Until it is, any request carrying one returns 403 CLIENT_MARKUP_NOT_ENABLED. Contact Conduit to enable it.
An active customer, and whatever that movement needs on its own — see Transact.
Your API key.

Which movements can carry a margin

Movement	Where you declare it
A conversion — on-ramp, off-ramp, crypto to crypto, fiat to fiat	`markupBps` / `markupAmount` on `POST /v2/orders`
A fiat payout	`markupBps` / `markupAmount` on `POST /v2/payouts`
The chained payout leg of a conversion	`markupBps` / `markupAmount` inside the order’s `autoPayout` block. Fiat legs only — a crypto leg refuses one, like a standalone crypto payout.
A crypto payout	Not available. Collecting a margin there needs a fee taken out of the customer’s own wallet, which needs that customer’s signers. Take the margin on the conversion that funds the payout instead.
A deposit	Not available. See Charge a fee on a deposit.

The two shapes

Send one, both, or neither.

Field	What it is	How your customer pays it
`markupBps`	A percentage, in basis points, to two decimal places. Minimum `0.01`; no configured maximum.	On a conversion it widens the quoted rate: `endUserRate` and `totalSpreadBps` already include it, so it never appears in `fees[]` and never moves `totalDebit`. On a payout there is no rate to widen, so it is charged on the amount moved, as a fee on top.
`markupAmount`	A flat amount per movement, in the source asset, at that asset’s precision. A finer value is refused rather than rounded down.	Charged like a fixed fee. On a source-locked order it carves out of the principal and your customer receives less; on a destination-locked order it adds to `totalDebit` and your customer pays more. On a payout it is charged on top, like `markupBps`.

Step 1 — Declare a margin on a conversion

curl https://api.conduit.financial/v2/orders \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "source":      { "type": "wallet", "id": "wlt_...", "asset": { "code": "USDC", "chain": "ethereum" } },
    "destination": { "type": "wallet", "id": "wlt_...", "asset": { "code": "USDT", "chain": "tron" } },
    "lockSide": "source",
    "amount": "100",
    "markupBps": 50,
    "markupAmount": "1.00"
  }'

The order echoes what you declared and what it will earn you:

{
  "id": "ord_034A21OFtmes4Wr3HCKgkH",
  "rate": { "referenceRate": "...", "totalSpreadBps": "...", "endUserRate": "..." },
  "fees": [
    { "type": "fixed", "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "0.500000" }, "owner": "conduit" },
    { "type": "fixed", "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "1.000000" }, "owner": "you" }
  ],
  "markup": {
    "bps": 50,
    "flatAmount": { "code": "USDC", "chain": "ethereum", "amount": "1.000000" },
    "assetAmount": { "code": "USDC", "chain": "ethereum", "amount": "1.492500" }
  }
}

markup.assetAmount is the whole margin — the percentage part plus the flat part — in the order’s source asset, fixed at quote time. The percentage is charged on the principal, not on the amount you sent: on a source-locked order the principal is amount less Conduit’s fee and less your flat margin, so 50 bps here earns 98.50 x 0.005 = 0.4925 on top of the 1.00 flat. owner on each fees[] entry tells the two charges apart: conduit is Conduit’s fee, you is your own money. Only the flat part appears there, because the percentage is already inside endUserRate.

A margin that comes to less than one minor unit of the source asset accrues nothing, and markup is then absent from the response. The rate still carries the percentage. Declaring 1 bps on a USD 1.00 order is the case to watch.

markupBps cannot ride a quote redemption — the locked rate is never recomputed, so there is nothing to fold it into. markupAmount works there and always adds to totalDebit.

Step 2 — Declare a margin on a fiat payout

curl https://api.conduit.financial/v2/payouts \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "customerId": "cus_034A21OFtmes4Wr3HCKgkH",
    "virtualAccountId": "vac_034A0gCCW1I7ZiTVLb0G7I",
    "assetAmount": { "code": "USD", "amount": "500.00" },
    "destination": { "type": "fiat", "rail": "fedwire", "recipient": { "...": "..." } },
    "purpose": "payment_for_goods_or_services",
    "documents": ["doc_034A0gCCW6w2ubcipmRoY8"],
    "markupBps": 50,
    "markupAmount": "1.00"
  }'

The full request shape is in Send a payout. Your recipient still receives assetAmount in full. The customer’s account is debited that amount plus Conduit’s fee plus your margin. Read it back on the payout’s fees[] as the entry with owner: "you".

fees[] attribution is as of the read. If the receiving bank returns the payout, Conduit no longer owes you the margin, and GET /v2/transactions/{id} then reports the whole charge as Conduit’s. A transaction.completed you already received keeps the attribution it was delivered with, so reconcile the reversal from transaction.failed with returned_by_sender — not by re-reading fees[] and diffing.

To take a margin on the payout leg chained to a conversion, put the same two fields inside the order’s autoPayout block. That leg spends the order’s converted output, so the margin comes out of it: your recipient receives destinationAsset.amount less your margin and less Conduit’s payout fee. It is separate from the conversion’s own markup, and it accrues when the payout succeeds.

Step 3 — Read what you earned

A margin accrues when the movement succeeds, never before. A movement that never succeeds accrues nothing. A fiat payout that succeeded and was later returned by the receiving bank is the one case that is not either/or, and it has three shapes. If the monthly sweep had already claimed the accrual when the return opened, the reversal posts a second, negative line against the same transaction id — expect two lines for that payout and net them. If the return opened first, the sweep never claims it at all, and the payout contributes no line. Rarely, a returned payout keeps its positive line alone, unreversed — Conduit detects those and corrects them, and you need do nothing. Reconcile for all three shapes; neither a missing line nor an unreversed one is a discrepancy on your side.

curl https://api.conduit.financial/v2/markup/balances \
  -H "x-api-key: YOUR_API_KEY"

{ "data": [{ "code": "USD", "amount": "1250.00" }, { "code": "USDC", "chain": "ethereum", "amount": "310.000000" }] }

That is what Conduit owes you and has not yet paid, one entry per asset. An asset you have never earned in is absent rather than zero. For the movements behind it, read GET /v2/markup/statement-lines — one line per movement, newest first, over conversions and payouts alike. Each line names the movement, the percentage and flat amount you declared, what it accrued, the end customer, and when it succeeded.

Getting paid

Balances are paid monthly against a statement, one per asset per calendar month in UTC. Read them at GET /v2/markup/statements.

`status`	What it means
`open`	The current month. Still accumulating.
`due`	Closed and payable. Conduit settles it.
`carried_forward`	Closed without being payable. It covers a total below Conduit’s minimum payout for that asset, and a negative total; both move into the next period as its `carriedIn` and are settled once the running total clears the minimum. A total of exactly zero also closes here, but it carries nothing forward and names no successor — the chain simply ends.
`paid`	Settled. `paymentReference` carries the reference.

A line can be negative. If a receiving bank returns a payout you took a margin on, Conduit no longer holds your customer’s money and no longer owes you the margin, so the reversal posts as a negative line on the open statement and reduces what that period settles.

Errors

Code	Cause
`CLIENT_MARKUP_NOT_ENABLED`	Margin is not enabled for your organization.
`CLIENT_MARKUP_SPREAD_EXCEEDED`	Your percentage plus Conduit’s own spread on that pair would take the quoted rate to zero. The error names how much room is left.
`CLIENT_MARKUP_EXCEEDS_PAYOUT`	The margin on a chained payout leg, plus Conduit’s own payout fee, reaches the converted output that funds it. Both come out of that one amount. The error names the room left.
`VALIDATION_ERROR`	`markupBps` sent with `quoteOptionId`; a margin sent on a crypto payout; or a `markupAmount` finer than the asset’s precision.

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Prerequisites

Which movements can carry a margin

The two shapes

Step 1 — Declare a margin on a conversion

Step 2 — Declare a margin on a fiat payout

Step 3 — Read what you earned

Getting paid

Errors

See also

​Prerequisites

​Which movements can carry a margin

​The two shapes

​Step 1 — Declare a margin on a conversion

​Step 2 — Declare a margin on a fiat payout

​Step 3 — Read what you earned

​Getting paid

​Errors

​See also

Prerequisites

Which movements can carry a margin

The two shapes

Step 1 — Declare a margin on a conversion

Step 2 — Declare a margin on a fiat payout

Step 3 — Read what you earned

Getting paid

Errors

See also