Gyvar docs
API reference v1Addresses

List addresses

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.

GET
/addresses

Authorization

KeyID Timestamp Nonce Signature
X-Gyvar-Key<token>

Your key id, gyv_k_live_... or gyv_k_sandbox_....

In: header

X-Gyvar-Timestamp<token>

Unix seconds. Must be within 5 minutes of our clock.

In: header

X-Gyvar-Nonce<token>

A unique value per request. Replays are rejected.

In: header

X-Gyvar-Signature<token>

Ed25519 signature over the canonical string. See the Signing guide.

In: header

Query Parameters

chain?string

Filter to one chain.

Value in

  • "bitcoin"
  • "tron"
  • "ethereum"
  • "polygon"
  • "solana"
  • "base"
  • "bsc"
reference?string

Filter to the addresses you tagged with this reference.

limit?integer

1-100. Values above 100 are clamped, not rejected.

Range1 <= value <= 100
Default50
cursor?string

The next_cursor from the previous page. Opaque - do not construct or parse one. A malformed cursor is a 400, never a silent reset to page one, because on a paginated sweep that would mean starting over without noticing.

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/addresses"
{  "data": [    {      "id": "0d6c2f3a-1b4e-4c9a-9f2d-7a1e5c8b3d60",      "chain": "bitcoin",      "address": "0x2f1a9C4b7E3d5A8f6B0c1D4e7A9b2C5d8E3f6A1b",      "assets": [        "USDT",        "USDC"      ],      "label": "Ama Owusu",      "reference": "customer_8842",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string"}

Create or fetch an address

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.

Balances

What the project's wallet holds, per asset.