Wallets & keys

Once an order settles, the wallets are yours. They keep their whole history (balance, age, transaction count, tier, persona) and gain three fields: the sale they came from, the price they went out at, and a buyer_ref if you set one.

Your inventory

GET /wallets lists the wallets your organisation owns. It is cursor-paged and filterable by chain and buyer_ref.

curl -X GET "https://example.com/wallets"

{  "items": [    {      "aging_status": "string",      "balance": "string",      "buyer_ref": "string",      "chain": "string",      "cost_basis": "string",      "created_at": "string",      "first_tx_at": "string",      "funded_at": "string",      "funding_exchange": "string",      "funding_source": "string",      "id": "string",      "imported": true,      "last_tx_at": "string",      "network": "string",      "owner_org_id": "string",      "persona_name": "string",      "pubkey": "string",      "sale_id": "string",      "sold_at": "string",      "source_kind": "string",      "status": "string",      "target_age_days": 0,      "tier": "string",      "timezone_name": "string",      "token_holdings": [        {          "balance": "string",          "decimals": 0,          "mint": "string",          "symbol": "string",          "ui_multiplier": "string",          "usd_value": 0        }      ],      "tx_count": 0,      "user_price": "string"    }  ],  "next_cursor": "string"}

Getting a key

GET /wallets/{id}/key returns one wallet's private key. It works for any wallet you own, whichever order it came from, which makes it the endpoint to use long after the purchase. GET /quote/{id}/keys is the other one: it hands back a whole lot at once, and it is what you call right after settlement.

Both are idempotent and neither consumes anything. For what happens to a key while we are still holding it, see Security.

curl -X GET "https://example.com/wallets/string/key"

{  "chain": "string",  "private_key_hex": "string",  "pubkey": "string",  "purged_at": "string",  "wallet_id": "string"}

Key formats

The field is called private_key_hex, and on Solana it is not hex. The encoding follows what each ecosystem's wallets actually import.

Solana wallets reject hex, and they reject the bare 32-byte seed too, so there was not much of a choice. Read the chain field on the response and decode accordingly.

When the key is gone

If your organisation has opted into key retention, we stop holding the keys of the wallets you buy a set number of minutes after the sale. Past that window the response still comes back, but with private_key_hex: null and purged_at set to the moment it was dropped.

Buyer references

buyer_ref is a free-text label you attach to wallets and orders. Nothing in the API interprets it. It exists so you can answer "which of my customers has this wallet". You can set it at quote creation, at settlement, or afterwards.

Four endpoints manage it after the fact:

• PUT /wallets/{id}/owner sets or clears it on one wallet.
• POST /wallets/reassign moves every wallet from one reference to another and returns how many moved.
• POST /wallets/unassign clears one reference across the board.
• GET /wallets/users lists the distinct references currently in use, which is the raw material for a customer picker.

curl -X PUT "https://example.com/wallets/string/owner" \  -H "Content-Type: application/json" \  -d '{}'

{  "ok": true}

curl -X POST "https://example.com/wallets/reassign" \  -H "Content-Type: application/json" \  -d '{    "from_buyer_ref": "string",    "to_buyer_ref": "string"  }'

{  "count": 0}

curl -X POST "https://example.com/wallets/unassign" \  -H "Content-Type: application/json" \  -d '{    "buyer_ref": "string"  }'

{  "count": 0}

curl -X GET "https://example.com/wallets/users"

"string"

Putting money in them

Wallets bought here arrive with whatever balance they had. To add native currency, to them or to any address you own elsewhere, see Top up wallets.