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.
Authorization
KeyID Timestamp Nonce Signature Your key id, gyv_k_live_... or gyv_k_sandbox_....
In: header
Unix seconds. Must be within 5 minutes of our clock.
In: header
A unique value per request. Replays are rejected.
In: header
Ed25519 signature over the canonical string. See the Signing guide.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A chain that can hold a standing receive address. lightning is
deliberately absent - see the Addresses tag.
Value in
- "bitcoin"
- "tron"
- "ethereum"
- "polygon"
- "solana"
- "base"
- "bsc"
Required. Your identifier for whatever this address is for - a customer, an invoice, a cost centre. It doubles as the idempotency key: the same reference always returns the same address, so a retry after a timeout cannot mint a second one.
There is no way to omit it. That would mean the project's standing address for the chain, which is created in the dashboard.
length <= 120A human-readable note. Display only; never used for routing.
length <= 120Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/addresses" \ -H "Content-Type: application/json" \ -d '{ "chain": "base", "reference": "customer_8842", "label": "Ama Owusu" }'{ "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" }}