Overview
Move value from a Bitcoin or stablecoin balance to a local destination.
The Gyvar API is a signed, server-to-server surface at https://api.gyvar.com/v1.
What you can do today
Receive addresses
An on-chain address per customer or invoice, keyed on your own reference.
Transactions
Every movement, both directions, newest first. Not summable - see Balances.
Corridors
Where we can pay out to right now - read it, do not hardcode it.
Beneficiaries
The payout destinations you saved. Read only - saving one stays a human action.
Payouts
Pay out in local currency to mobile money or a bank account.
Transfers
Send BTC, USDT or USDC on-chain.
Lightning
Mint an invoice per payment, or pay one.
Balances
What the business's wallet holds, per asset. The authority for balance.
Webhooks
Get told when money lands or a payout settles.
Start here
- Get access. Keys are self-serve in both sandbox and live, a key that sends money needs an IP allowlist, and moving money needs one grant you have to ask for. Two minutes, and it explains every 403 you might meet on day one.
- Sign a request. Ed25519, four headers, one canonical string. This is the only genuinely fiddly part, and it is fiddly in the same way for everyone - read it before writing code.
- Run the quickstart. Create an address in sandbox and watch a webhook arrive.
- Read the error contract. Switch on
details.code, never onmessage.
Two things to get right up front
Amounts. Every amount comes back twice: amount is a decimal string in the major
unit, amount_minor an integer in the minor unit. Display amount. Do arithmetic on
amount_minor. Parsing amount as a float is the bug that surfaces months later, on
someone else's money.
Idempotency. Two mechanisms, because the two halves of this API fail differently.
On reads and receives the key is a field you already send - reference on an address -
so a retried call returns the same resource rather than a second one. On
money-moving endpoints it is the Idempotency-Key header, and it is required:
retry a timed-out payout without one and you would pay twice, which is the one mistake
here that cannot be undone by trying again.
A key issued today cannot spend
A key is read-only unless you ask for more. Reads work the moment you hold one;
minting an address or an invoice needs the receive capability, and the endpoints
that send money need two further grants - the money capability on the
key, and the business opened for money over the API - with neither sufficient alone.
That is what keeps a leaked key from paying anybody. See Access.