Fees and sending

CoinVertus API: network fees, source selection, send plans, confirmation, tasks and their statuses.

Contents

API address: https://api.coinvertus.net/v1

Sending: the flow

getfee — network fee at the fast, normal, low levels and the service fee; spendinfo — which addresses the funds will come from.
preparetx — the transfer plan: sources, recipients, fee, steps. The plan reserves nothing and lives 5 minutes (expires_at).
Check the plan and confirm it: posttx with prepare_id and confirm = HMAC-SHA256(key secret, “key_id.fingerprint.prepare_confirm.prepare_time”), where key_id is the ID of the key that prepared the plan.
posttx queues the task and charges the service fee; the queue sends the transfer within seconds. The outcome — task/{TASK_ID} or the task.done webhook.

Field	Description
`to`	Recipients: address and amount; tag is a destination tag, comment is a text for the recipient up to 120 characters where the network supports it. Several recipients (up to 100) only for pairs with multi_recipient; with send_all — one recipient without amount.
`from`	Your source addresses (address); without from, addresses are picked automatically. In account-based networks — one address.
`order`	Source selection order: desc (default) — larger addresses first, asc — smaller first.
`fee`	preparetx: fast, normal (default) or low; in UTXO networks also a numeric rate in fee_rate_unit. In account-based networks only normal; for tokens that pay for energy also rent or burn.
`change`	preparetx, UTXO networks: where change goes — auto (default, the address of the largest input), new (a new address) or your own address in this network.
`send_all`	preparetx: true sends everything from the sources minus the fee.

getfee and spendinfo

getfee takes the same to, from, order. fee_coin is the network fee coin (for a token — the network coin); fast, normal, low are amount plus five currencies, or null when the network has no such level or the amount with the fee does not fit at it (fits nowhere — 409 A018); service_fee_usd is the service fee; extra lists additional costs.

{
    "coin": "DOGE",
    "network": "dogecoin-mainnet",
    "fee_coin": "DOGE",
    "fast": {
        "amount": "0.04452",
        "usd": "0.2",
        "eur": "0.01",
        "rub": "0.5",
        "cny": "0.04",
        "inr": "0.47"
    },
    "normal": {
        "amount": "0.02226",
        "usd": "0.1",
        "eur": "0.01",
        "rub": "0.5",
        "cny": "0.04",
        "inr": "0.47"
    },
    "low": null,
    "service_fee_usd": "0.10",
    "extra": []
}

`extra.type`	Meaning
`gas`	The token address lacks the network coin: amount will come to it from another of your addresses, network_fee is the fee of that transfer.
`rent`	Without provider — creating the recipient token account, if it does not exist yet.
`burn`, `rent`	With provider — ways to pay for token energy: burning (burn) or renting (rent); selected marks the way fee normal will choose.

spendinfo takes to and order. sources are funded addresses in order: address, balance (available), locked (busy with an unfinished transfer), use — how much sending will take from it; enough tells whether it is sufficient. For a token use is the token amount; getfee and preparetx check the fee.

preparetx: the send plan

Request: network, to, from, order, fee, change, send_all. Response: the plan and the data to confirm it in posttx. Not enough payment balance for the service fee — 409 A020.

{
    "prepare_id": "prep_9a3f0c7d21b84e65f0a1c2d3",
    "prepare_confirm": "5c0e8d1f7a2b4c6d9e3f1a0b2c4d6e8f",
    "prepare_time": 1789647000,
    "expires_at": "2026-09-17T12:15:00Z",
    "fingerprint": "0995342725a2b11aa2260e7e84e6394754eef9dcc7412a222e2952b9d9589345",
    "coin": "DOGE",
    "network": "dogecoin-mainnet",
    "tx": {
        "sources": [
            {
                "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
                "amount": "150.5"
            }
        ],
        "recipients": [
            {
                "address": "D8vFz4p1L37jdg47HXKtSHA5uYLYxbGgPD",
                "amount": "100"
            }
        ],
        "change": {
            "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
            "amount": "50.47774"
        },
        "network_fee": "0.02226",
        "fee_coin": "DOGE",
        "fee_rate": "100",
        "fee_rate_unit": "koinu/vB",
        "size": 226,
        "replaceable": false
    },
    "steps": [
        {
            "type": "send"
        }
    ],
    "service_fee_usd": "0.10"
}

Field	Description
`tx.sources`	Source addresses and how much leaves each one, network fee included.
`tx.recipients`	Recipients and amounts; in networks with a tag or comment — tag and comment.
`tx.change`	UTXO change: address and amount; no change — null.
`tx.network_fee`, `tx.fee_coin`	Network fee and its coin.
`tx.fee_rate`, `tx.fee_rate_unit`, `tx.size`, `tx.replaceable`	UTXO networks: rate and its unit, transaction size, whether it can be replaced by a transaction with a higher fee.
`tx.fee_payer`, `tx.rent`	Tokens whose fee is paid by another of your addresses in the same transaction: that address and the charge for creating the recipient account.
`steps`	Execution steps: gas — topping up gas first (from, to, amount, network_fee), rent — renting energy (provider, energy, cost), send — the transfer itself.
`expires_at`, `fingerprint`	Plan expiry and fingerprint: the plan can be confirmed only before expires_at.

posttx and the task

posttx takes prepare_id and confirm and returns the task object. Repeating it with the same prepare_id returns the same task, even after the plan expires, so posttx is safe to retry after a lost connection. A plan of another key or account — 404 A021, expired — 409 A021, wrong confirm — 400 A002. task/{TASK_ID} returns the same object.

{
    "task_id": "task_6f1c2a9b0d4e8f7a3c5b1d20",
    "task_info": "confirmed",
    "task_start": "2026-09-17T12:10:00Z",
    "task_sent": "2026-09-17T12:10:04Z",
    "task_done": "2026-09-17T12:20:12Z",
    "prepare_id": "prep_9a3f0c7d21b84e65f0a1c2d3",
    "coin": "DOGE",
    "network": "dogecoin-mainnet",
    "txid": "b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7",
    "gas_txid": null,
    "confirmations": 6,
    "error_code": null,
    "tx": {
        "sources": [
            {
                "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
                "amount": "150.5"
            }
        ],
        "recipients": [
            {
                "address": "D8vFz4p1L37jdg47HXKtSHA5uYLYxbGgPD",
                "amount": "100"
            }
        ],
        "change": {
            "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
            "amount": "50.47774"
        },
        "network_fee": "0.02226",
        "fee_coin": "DOGE",
        "fee_rate": "100",
        "fee_rate_unit": "koinu/vB",
        "size": 226,
        "replaceable": false
    },
    "service_fee_usd": "0.1"
}

`task_info`	Meaning
`queue`	Queued; the task can be cancelled.
`processing`	Being sent.
`gas`	Waiting for the token gas top-up to confirm.
`rent`	Waiting for the energy rental.
`sent`	In the network, waiting for confirmations.
`unknown`	The send outcome is unknown: the node did not answer. Do not repeat the transfer — reconciliation will settle it and the task will move on by itself.
`confirmed`	Confirmed.
`failed`	Not done — the reason is in error_code.
`dropped`	The transaction dropped from the network without confirmations.
`cancelled`	Cancelled by the client.

Field	Description
`task_start`, `task_sent`, `task_done`	Queue time, send time and final status time; not yet — null.
`txid`, `gas_txid`, `confirmations`	Transfer transaction, gas top-up transaction and confirmations; before sending — null.
`error_code`	Reason code if the task was not done; otherwise null.
`tx`, `service_fee_usd`	The plan from preparetx and the service fee charged for the task.

`error_code`	Meaning
`A009`	The network or node was unavailable for more than 30 minutes, or the send outcome is unknown.
`A018`	By the time of sending, the address lacked funds.
`A021`	The plan is outdated (balance, fee or address changed after preparetx) or the account is blocked.
`A023`	The network rejected the transaction; the network fee was charged.
`A025`	The energy rental failed.

task/{TASK_ID}/cancel cancels a task in queue — before the first attempt and between retries; once gas is sent or a rental is ordered, it cannot be cancelled. Later — 409 A024. Repeating it for a cancelled task returns that task.

Network specifics

UTXO networks: several recipients, fast, normal, low levels or your own rate, change via change; sources are inputs from your addresses.
Account-based networks: one source address and one recipient, only normal. An address with an unfinished transfer is busy until it confirms — the task waits up to 30 minutes.
Networks with destination tags (tag in assets): to[].tag goes to the recipient; incoming transfers to your address differ by tag in transfers, and getnewaddress issues a new tag for the same address.
A network with transfer comments: to[].comment is a text up to 120 characters; other networks reject the field (400 A002).
Tokens: the fee is paid in the network coin from the same address. If it is short, the plan starts with a gas step: a top-up from your largest free address in the network, and the token leaves after it confirms.
Tokens that pay for energy: fee normal rents from the cheapest connected provider, otherwise burns; rent or burn chooses manually. A failed rental — failed A025. Providers are connected in account settings, the “Helpers” tab.
Tokens whose fee and recipient account creation are paid in the same transaction by your address with the most network coin: tx has fee_payer and rent, there is no gas step.
Private networks: sending from one address, getfee is an upper estimate, the exact fee is in preparetx, privkey is unavailable; sending through the node wallet takes up to a few minutes.

Service fee and payment balance

The service fee follows your plan: a percent of the USD amount with a minimum and maximum; getfee and preparetx show it (service_fee_usd). It is charged from the payment balance on posttx and returned if the transfer did not reach the network, dropped or the task was cancelled. A confirmed transfer and one rejected by the network (failed A023) do not return it.

To keep sending from stalling on the balance, turn on auto top-up in your account (Payment balance → Auto top-up); the paybalance.low webhook warns when the balance falls below the threshold.