Gyvar API documentation

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.

Every endpoint that returns a transaction returns this shape, wrapped in a data envelope.

Attributes

`id`

uuid · always present

Always present. The only field safe to key on.

`direction`

enum · always present

— One of: in, out.

Three states, one vocabulary, both directions and every rail. A deposit is always successful: the ledger is credited only at confirmation, so an unsettled deposit has no row here at all. pending means keep checking - it covers every in-flight state of a payment, and it is never a partial success. Only successful and failed are terminal. One of: successful, failed, pending.

`currency`

string · always present

—

`decimals`

integer · always present

—

`amount`

string · always present

Gross movement, before our fee. The main field.

`amount_minor`

string · always present

—

`fee`

string · always present

Deducted from amount, never added.

`fee_minor`

string · always present

—

`net`

string · always present

amount - fee. What crossed to or from the outside world.

`net_minor`

string · always present

—

`created_at`

timestamp · always present

—

`reference`

string · optional

Our handle for this movement: DEP_… inbound, WDR_… outbound, so the prefix tells you which half of the feed it came from. Optional - a direct on-chain receive mints no movement row and so has none. Use id when you need something always present, and treat the whole string as opaque: deposits from before September 2026 carry CTX_ or LNX_ and are deliberately not rewritten.

`chain`

enum · optional

The chain the money settled on. Absent on a fiat payout, which carries settlement_* and destination instead. Lightning settles on bitcoin - it is a network on that chain, not a chain of its own - so switch on network, not on this. One of: bitcoin, tron, ethereum, polygon, solana, base, bsc.

`network`

enum · optional

How the money moved on that chain, and the field to switch on: - chain: bitcoin, network: lightning -> invoice + payment_hash - network: onchain (any chain) -> address + hash - neither present -> a fiat payout Distinct from destination.network, which names the mobile-money network or bank inside a fiat payout. The two never appear on the same row. One of: onchain, lightning.

`address`

string · optional

—

`hash`

string · optional

Settlement identifier. Absent on a failed payment - nothing settled.

`invoice`

string · optional

Lightning bolt11.

`payment_hash`

string · optional

—

`address_reference`

string · optional

(in) YOUR tag on the address the money landed on, when you generated it with one. Named address_reference and not reference on purpose: they are different things, and one name meaning two things by direction is what a typed client gets wrong.

`address_label`

string · optional

(in) Your note on that address. Display only.

`completed_at`

timestamp · optional

(out) Set once the order reached a terminal success.

`failure_code`

enum · optional

(out) Present only on a failed payment. A deliberately small closed set, so it is safe to switch on. One of: transfer_failed, payout_failed.

`failure_message`

string · optional

(out) A short, stable reason. Never raw upstream text.

`settlement_currency`

string · optional

(out, fiat) What the beneficiary actually received.

`settlement_decimals`

integer · optional

(out, fiat) Always published. UGX is zero-decimal, and XOF, XAF and RWF are the same trap - assuming 2 is wrong by a factor of 100 there.

`settlement_amount`

string · optional

—

`settlement_amount_minor`

string · optional

—

`rate`

string · optional

(out, fiat) The EFFECTIVE customer rate, our FX markup already inside it, such that settlement_amount = net x rate. Never the partner rate.

`destination`

object · optional

(out, fiat) Masked: last four and the network or bank, never the full account number and never the account-holder name. You already hold the beneficiary.

The Transaction object

{
  "id": "0d6c2f3a-1b4e-4c9a-9f2d-7a1e5c8b3d60",
  "direction": "in",
  "status": "successful",
  "currency": "USDC",
  "decimals": 6,
  "amount": "20.000000",
  "amount_minor": "20000000",
  "fee": "0.600000",
  "fee_minor": "600000",
  "net": "19.400000",
  "net_minor": "19400000",
  "created_at": "2026-09-01T10:04:11Z",
  "reference": "WDR_TBJWZFYIYTM3KPF5",
  "chain": "ethereum",
  "network": "onchain",
  "address": "<address>",
  "hash": "<hash>",
  "invoice": "<invoice>",
  "payment_hash": "<payment_hash>",
  "address_reference": "<address_reference>",
  "address_label": "<address_label>",
  "completed_at": "2026-09-01T10:04:11Z",
  "failure_code": "transfer_failed",
  "failure_message": "<failure_message>",
  "settlement_currency": "GHS",
  "settlement_decimals": "<settlement_decimals>",
  "settlement_amount": "<settlement_amount>",
  "settlement_amount_minor": "<settlement_amount_minor>",
  "rate": "<rate>",
  "destination": "<destination>"
}

The Transaction object

Attributes

`id`

`direction`

`status`

`currency`

`decimals`

`amount`

`amount_minor`

`fee`

`fee_minor`

`net`

`net_minor`

`created_at`

`reference`

`chain`

`network`

`address`

`hash`

`invoice`

`payment_hash`

`address_reference`

`address_label`

`completed_at`

`failure_code`

`failure_message`

`settlement_currency`

`settlement_decimals`

`settlement_amount`

`settlement_amount_minor`

`rate`

`destination`

On this page