Vaults and addresses

A vault is where your organisation holds money. You decide what each one is for: one per customer, one for your treasury, one for each team that pays out. Every vault has an address, and it is the same address on every network Sotirea supports, so a customer can be shown one address whatever they pay with.

How a vault works

Each vault is a smart account: a small program on each network that holds the money and only moves it when Sotirea’s signer authorises it, under your organisation’s rules. That is what lets one address exist on every network, and what lets Sotirea add a network later without your customers’ addresses changing.

Opening a vault touches no network and costs nothing. Its address is worked out in advance, so it can receive straight away, and Sotirea starts watching it on every network at once. The account itself is created on a network the first time the vault pays out there. That first payment waits as awaiting_gas while the account is created, its fee is a little higher, and a quote says so with includes_vault_creation. After that, payments from the vault on that network cost the usual fee.

One vault per customer

Give a vault a reference, your own id for whatever it is for, such as your customer’s id:

POST /v1/vaults
{ "reference": "cust_1001", "name": "Ada Obi" }

• A new reference opens a vault, answered 201.
• The same reference again answers that same vault, 200, unchanged. So you can ask for a customer’s vault whenever you need it, without remembering whether you opened it already. Two requests at the same moment still open only one.
• The same reference with a different name is refused 409: a reference names one vault.

A reference is 1 to 128 characters with no spaces, unique in your organisation and kept exactly as you gave it. Without a name, the reference is used as the name. Find a vault by reference with GET /v1/vaults?reference=cust_1001. Deposits carry vault_reference, so you can credit the right customer without looking the vault up.

Addresses on each network

A vault lists one entry per network in addresses, each with the network’s id, its name, the address and whether the network is paused. Show a customer the address for the network they mean to pay with, and only where paused is false.

When Sotirea adds a network, every existing vault gets its address there, the same address again, and it is watched from then on.

Send only what the network carries

A vault receives the network’s own coin and any token on that network. An asset sent on a network Sotirea does not support, even to the same address, is not seen by Sotirea.

Refreshing a vault

If you think a vault is missing something it received, ask Sotirea to look again: POST /v1/vaults/{id}/refresh. It answers 202 at once, with a run for each network, and you follow it with GET /v1/refreshes/{id}. A refresh never writes a balance directly. It reads the network again and anything missing comes in the same way every deposit does, so it is credited, made final and announced like any other. A difference it cannot explain is raised with Sotirea’s team rather than corrected automatically.