Deposits and finality

When someone pays one of your vaults, Sotirea sees the payment shortly after the network includes it in a block. But a network can still drop a recent block and replace it with another, and a payment in a dropped block may never happen. Only after enough blocks have been built on top, or the network itself declares the block settled, can the payment no longer be undone. That point is finality, and Sotirea counts money only once it is final.

So a deposit has two states:

• arriving: seen on the network, not yet final. It shows in the vault’s balance as incoming, so you can tell a customer their payment is on its way. It cannot be spent.
• received: final. It is added to the vault’s available balance, credited_at is set, and it can be spent.

Credit your customer when a deposit is received, never while it is arriving. Webhooks tell you of both: deposit.arriving and then deposit.received.

How long it takes

Each network has its own way of becoming final. GET /v1/networks gives each network’s usual time, in seconds (finality_seconds) and in words (finality). Roughly:

Network	Usually final after
Ethereum, Arbitrum and Robinhood Chain	about 15 minutes
Base	about 21 minutes
BNB Smart Chain	a few seconds
Arc	about a second

Each test network takes about as long as its Live counterpart. Test networks are also read every two minutes rather than continuously, so a test deposit can take up to two minutes longer to appear.

If a network replaces blocks that held a deposit before it was final, the deposit is dropped, and anything the new blocks still contain comes back. If a network ever replaced a block Sotirea had already counted as final, nothing is changed automatically: Sotirea’s team is alerted to look at it.

What counts as a deposit

• The network’s own coin, such as ETH, sent to the vault’s address.
• Any token on the network, sent to the vault’s address. Tokens on Sotirea’s recognised list have recognised true. Any other token is credited too, with recognised false and whatever symbol its contract calls itself, which may imitate a real one. Do not credit a customer for an unrecognised token without checking it.
• A payment that failed on the network, or of zero, is not a deposit.

A deposit with sweep true is one of your own sweeps moving money between your vaults, not someone paying you. Do not credit a customer for it.

Coin moved by a contract, on Arbitrum and Robinhood Chain

Most coin arrives in a plain transfer from a wallet, and every token arrives with a record the network keeps, and both are seen on every network. Coin can also be moved by another contract as part of what it does, such as an exchange paying out. On Arbitrum and Robinhood Chain, coin moved that way to a vault that has not yet made its first payment on that network is not seen automatically. If a customer says they paid and nothing arrived, ask Sotirea to look again with POST /v1/vaults/{id}/refresh: it finds the payment and credits it like any other deposit.

Balance fields

GET /v1/balances answers one row per vault, network and asset. Every amount is a string of the asset’s smallest unit: 1.5 ETH is "1500000000000000000", and decimals says how to scale it for a person.

Field	What it holds
available	Final. Everything the vault holds and nothing can take back.
incoming	Seen arriving, not yet final.
outgoing	Seen leaving, not yet final.
reserved	Promised to payments already accepted and not yet final.
held	Held for a compliance review. See sanctions screening.
spendable	What a new payment can use: available, less reserved and held. Show this as what can be sent.