> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.
# Take your own margin
> Declare your own margin on the conversions and payouts you start, read what it earned, and get paid monthly against a statement
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](/guides/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](/sandbox/quickstart), then [conversion
simulation](/sandbox/conversions), and the [cheat
sheet](/sandbox/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`](/errors#client-markup-not-enabled). Contact Conduit to enable it.
* An `active` customer, and whatever that movement needs on its own — see [Transact](/guides/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`](/api-reference/orders/create-an-order) |
| A fiat payout | `markupBps` / `markupAmount` on [`POST /v2/payouts`](/api-reference/payouts/create-a-payout) |
| 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](/guides/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
```bash theme={null}
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:
```json theme={null}
{
"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](/guides/quote-before-you-order#redeem-the-option) — 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
```bash theme={null}
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](/guides/send-payout#request-body).
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.
```bash theme={null}
curl https://api.conduit.financial/v2/markup/balances \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
{ "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`](/api-reference/markup/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`](/api-reference/markup/monthly-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`](/errors#client-markup-not-enabled) | Margin is not enabled for your organization. |
| [`CLIENT_MARKUP_SPREAD_EXCEEDED`](/errors#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`](/errors#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`](/errors#validation-error) | `markupBps` sent with `quoteOptionId`; a margin sent on a crypto payout; or a `markupAmount` finer than the asset's precision. |
## See also
* [Charge a fee on a deposit](/guides/charge-a-fee-on-a-deposit) — the one flow that carries no margin field, and what to do instead.
* [Convert crypto](/guides/convert) and [Send a payout](/guides/send-payout) — the movements a margin rides on.
* [Quote before you order](/guides/quote-before-you-order) — a quote is always priced without your margin.