Custom Fee

Use Custom Fee when your app needs Carbium to build a standalone transaction that contains a custom fee instruction.

GET https://api.carbium.io/api/v1/fee/custom

This page owns only the standalone custom-fee transaction builder. It does not quote a swap, choose a route, sign the transaction, submit it, or confirm it on-chain.

Part of the Carbium Solana infrastructure stack.

Where Custom Fee Fits

The endpoint is useful when your integration already knows:

which account should pay the fee transaction
which account should receive the fee
how many lamports should be transferred
where the returned transaction should be signed and submitted

It returns a base64 transaction payload. Treat that payload as a build artifact, not as a completed payment.

Question	Use this page when...	Use another page when...
Standalone fee transaction	You need `GET /api/v1/fee/custom` to build a fee transaction from `payer`, `receiver`, and `lamports`	You need a token swap transaction or route quote
Swap with app fee fields	You are only comparing the standalone custom-fee endpoint	You need `feeLamports` and `feeReceiver` inside the older `GET /api/v1/swap` flow
Submission	You already have a transaction payload to sign later	You need sign -> submit -> confirm guidance

For swap transaction building, use Swap. For command selection across the API, use API Commands.

Request Shape

Method: GET

URL:

https://api.carbium.io/api/v1/fee/custom

Headers:

X-API-KEY: YOUR_API_KEY
accept: application/json

Parameter	Required	Meaning
`payer`	Yes	Account that pays for the fee transaction
`receiver`	Yes	Account that receives the fee
`lamports`	Yes	Fee amount in lamports

Use the Swap API key in X-API-KEY. This endpoint is on api.carbium.io, not the Carbium RPC endpoint.

Minimal Request

curl --request GET 'https://api.carbium.io/api/v1/fee/custom?payer=YOUR_PAYER_ADDRESS&receiver=YOUR_RECEIVER_ADDRESS&lamports=10000' --header 'X-API-KEY: YOUR_API_KEY' --header 'accept: application/json'

Use real Solana account addresses for payer and receiver. Keep lamports in the smallest SOL unit; 10000 lamports is not 10000 SOL.

Response Shape

A successful response returns a transaction payload under feeTx.

{
  "success": true,
  "data": {
    "feeTx": "AQAAAA..."
  }
}

Field	How to use it
`success`	Confirms Carbium built the custom-fee transaction payload
`data.feeTx`	Base64 transaction payload for your app to deserialize, inspect, sign, and submit

Do not treat feeTx as proof that funds moved. The transaction still has to be signed by the required signer and submitted to Solana.

Validation Before Signing

Check the fee transaction before it leaves your backend or signer flow.

Check	Why it matters
`payer` is the intended paying account	Prevents charging the wrong wallet or signer
`receiver` is controlled by the intended recipient	Prevents unrecoverable fee routing mistakes
`lamports` matches your product policy	Avoids unit mistakes and accidental overcharging
The transaction is inspected before signing	The endpoint builds a payload; your app still owns final signing approval
Submission and confirmation are tracked	A built transaction is not the same thing as a landed transaction

If the custom fee is part of a swap workflow, keep the fee policy visible to users or operators before signing. Hidden fee behavior is a product and trust problem, not just an API detail.

Common Failure Patterns

Symptom	Likely cause	First fix
`401` with `API key missing`	The `X-API-KEY` header was not sent	Send the Swap API key in the request header
`404` on `/api/v2/fee/custom`	The documented custom-fee path is under `api/v1`	Use `https://api.carbium.io/api/v1/fee/custom`
No usable transaction payload	Required query fields are missing or malformed	Check `payer`, `receiver`, and `lamports` before debugging signing
Signing fails after `feeTx` returns	The build step succeeded; the failure moved to signer setup or transaction handling	Inspect the transaction and signer boundary before retrying

Use Swap API Errors Reference for auth and request-shape failures. Use Executing Swaps when the next problem is signing, submission, or confirmation.

Use Custom Fee for the standalone fee-transaction builder. Use Swap when the fee belongs inside a swap transaction, and start platform setup at carbium.io.