Network fees

Every payment on a network pays the network a fee, often called gas, in the network’s own coin: ETH on Ethereum and Base, BNB on BNB Smart Chain. Without a way to pay it, a vault holding only USDC could never send it.

Sotirea solves this with a gas pool: coin your organisation sets aside on each network to pay fees. The pool pays the fee for every payment out of every vault on that network. A vault never needs to hold the network’s coin, and the fee never comes out of the amount you send: send 100 USDC and 100 USDC arrives.

Topping up

Each network has its own pool. In the console, open Network fees, choose the network under Add coin, and send that network’s coin to the address shown. GET /v1/gas-pools answers each pool’s balance and address, so your own systems can watch it.

The fee taken is what the network actually charged, read from the payment’s receipt once it is mined, and every fee is a line in your ledger and your statements. A payment the network ran but rejected still pays its fee, as on any network.

Before you send

Quote a payment to see the most its fee can cost, in fee_ceiling, and whether the pool holds that much now, in gas_pool_covers. The quote changes nothing and reserves nothing.

A vault’s first payment on a network also creates the vault’s account there, so it costs more. The quote includes that and says so with includes_vault_creation. The payment is awaiting_gas while the account is created, then goes on by itself.

When the pool cannot pay

A payment the pool cannot pay for is not held until you top up. It fails: the request is answered 400 with fields.rule set to insufficient_gas, and the message names how much is short and the pool’s address. Nothing is sent and the vault’s money is released.

Because a repeated Idempotency-Key answers the payment it first created, sending the same request again would answer that failed payment. Top the pool up and send with a new Idempotency-Key.

Being told it is low

Someone who manages the gas pool can set, in the console, a level below which the pool counts as low. When the pool drops below it, Sotirea sends one gas.low webhook, with the network, the pool’s address and the level, and sends another only after the pool has been topped up above it and fallen again. The level is off until someone sets it.