# Documentation

- [Gyvar API](/docs): Move value from a Bitcoin or stablecoin balance to a local destination.
- [Quickstart](/docs/quickstart): From nothing to a sandbox address and a webhook in about ten minutes.
- [Signing a request](/docs/signing): Every Gyvar API request is signed with an Ed25519 keypair you generate. The cryptography is one call; the canonical string is what goes wrong.

- **Concepts**
- [Access](/docs/access): What a project needs before it can call this API, and the one thing you still have to ask us for.
- [Errors](/docs/errors): One envelope, snake_case, and a stable machine-readable code you switch on.
- [Pagination](/docs/pagination): Keyset cursors, newest first.
- [Sandbox](/docs/sandbox): Same host, same code, different universe. The key decides.
- [Webhooks](/docs/webhooks): How Gyvar tells you money landed, and how to verify that it was us.

- **Reference**
- API reference v1
  - [API reference](/docs/api): The signed server-to-server surface at https://api.gyvar.com/v1.
  - Addresses
    - [Addresses](/docs/api/addresses): Standing on-chain receive addresses.
    - [The Address object](/docs/api/addresses/object): The shape of an address wherever the API returns one.
    - [Create or fetch an address](/docs/api/addresses/createAddress): Get-or-create, keyed on the `reference` you send. Returns 201 when an address was minted and 200 when an existing one was returned; both are success, and the distinction lets you log which happened instead of having to trust us. A retry after a timeout returns the same address rather than minting a second one.

`reference` is required. Without one the request would mean "the project's standing address for this chain", and that address is the dashboard's - it is the one a person reads off the Wallet screen.
    - [List addresses](/docs/api/addresses/listAddresses): Keyset paginated, newest first. A next_cursor is present only on a full page, so its absence means you have reached the end and there is no final request that comes back empty.
  - Balances
    - [Balances](/docs/api/balances): What the project's wallet holds, per asset.
    - [The Balance object](/docs/api/balances/object): The shape of a balance wherever the API returns one.
    - [List balances](/docs/api/balances/listBalances): The project's per-asset wallet balances. Not paginated - the set is the asset catalog, and assets at zero are included.

This is the authority for balance. Summing the transaction feed gives a different, wrong number: a failed payment is one row there with zero balance impact.
  - Beneficiaries
    - [Beneficiaries](/docs/api/beneficiaries): The payout destinations this project has saved.
    - [The Beneficiary object](/docs/api/beneficiaries/object): The shape of a beneficiary wherever the API returns one.
    - [Fetch a beneficiary](/docs/api/beneficiaries/getBeneficiary): The other half of the join: a payment row publishes `destination.id`, and this is where that id resolves.

A destination that is not yours is a 404, never a 403. A destination you have since REMOVED is also a 404 - the payment itself still carries the masked account, which is the durable record of where the money went.
    - [List beneficiaries](/docs/api/beneficiaries/listBeneficiaries): Keyset paginated, newest first. `next_cursor` is present only on a full page.
  - Corridors
    - [Corridors](/docs/api/corridors): Where Gyvar can pay out to, right now.
    - [The Corridor object](/docs/api/corridors/object): The shape of a corridor wherever the API returns one.
    - [List banks for a corridor](/docs/api/corridors/listCorridorBanks): Payout institutions for a country with a `bank` method. Separate from the corridor row because the list is long and changes on its own schedule - fetch it when you are about to save a bank destination, not to render a corridor.
    - [List corridors](/docs/api/corridors/listCorridors): The payout capability catalog. Not paginated - it is a handful of countries.
  - Lightning
    - [Lightning](/docs/api/lightning): Receiving over Lightning.
    - [Create an invoice](/docs/api/lightning/createLightningInvoice): Mints a FRESH invoice every time. There is no get-or-create and there cannot be one: `/addresses` is idempotent on a reference you supply, but an invoice is amount-fixed and single-use, so the same trick does not apply.

**A request that times out and is retried mints a SECOND invoice.** That is cheap rather than dangerous - an unpaid invoice expires on its own, and only one can ever be paid, because the credit is keyed on the payment hash. The cost is showing the wrong one to a payer, so prefer one mint per payment attempt over blind retries.
  - Money
    - [Money](/docs/api/money): Sending value out of the wallet.
    - [Pay a beneficiary in local currency](/docs/api/money/createPayout): Prices and sends in ONE call. There is deliberately no quote endpoint: a quote locks a rate for five minutes, which is a courtesy to a person and a free option to a machine - poll quotes, execute the ones the market moved in your favour, let the rest lapse at no cost.

Use `min_settlement_amount_minor` to bound what you accept instead. It is checked BEFORE anything is debited, so a refusal costs you nothing.

`amount_minor` is what leaves your WALLET, in the asset's minor units. What the beneficiary receives depends on a rate that does not exist until we ask for it, which is why you state the side you are spending.
    - [Send on-chain](/docs/api/money/createTransfer): Sends BTC, USDT or USDC to an address on a chain. Lightning has its own route: it shares a rail internally and shares nothing in the shape of a destination.

`amount_minor` is in MINOR units, unlike the major strings this API publishes. An outbound amount is an instruction rather than a figure to display, and a decimal here would make the rounding your guess at the moment it matters most.
    - [Pay over Lightning](/docs/api/money/payLightning): Pays a bolt11 invoice or a Lightning address. Send one or the other, never both - two destinations on a money request is not something we will resolve for you.

An invoice carries its own amount, so `amount_sat` is REFUSED alongside one. A Lightning address carries none, so it is required there.
  - Transactions
    - [Transactions](/docs/api/transactions): Everything that happened to the project's balance, both directions, newest first.
    - [The Transaction object](/docs/api/transactions/object): One money movement. Fields marked *(in)* appear only on inbound rows and *(out)* only on outbound ones; a field with nothing to say is omitted rather than sent empty.
    - [Fetch a transaction](/docs/api/transactions/getTransaction): Same shape as one row of the list. Resolves ids from both spaces.

A transaction that is not yours is a 404, never a 403: the difference between those two answers would itself tell you which ids exist.
    - [Fetch a transaction by reference](/docs/api/transactions/getTransactionByReference): Same shape as one row of the list, looked up by the handle we print and webhook rather than by our uuid - `DEP_…` for a deposit, `WDR_…` for a payment.

Use this when what you hold came off a webhook, a receipt or a support thread. Both spaces are searched whatever the prefix, so a deposit from before September 2026 (`CTX_`/`LNX_`) still resolves.

Not every transaction has one: a direct on-chain receive mints no movement row and so has no reference. Those are reachable by `id` only.
    - [List transactions](/docs/api/transactions/listTransactions): Keyset paginated, newest first, both directions merged. `next_cursor` is present only on a full page.

Filtering is server-side: a page filtered after it arrives is filtered against fifty rows, not against your history.