Wallets

A wallet tells the gateway where a store receives payments on one network in watch-only processing: the gateway derives a fresh address per payment intent from your extended public key, so payments go straight to addresses you control and every transfer maps unambiguously to one intent.

Live payments do not use receive wallets

This platform does not use watch-only processing for payments. Live payments are processed through the platform’s Bitcart account instead: customers pay the platform’s wallets and GRYPHEM PAY holds the funds on your behalf as a custodial balance, which you withdraw through payouts to allow-listed addresses. You do not need a receive wallet to accept payments. See Custody.

Never send private keys

GRYPHEM PAY only ever needs an extended public key. It will never ask for a private key, seed phrase or wallet file. If any interface asks you for one, stop and report it.

POST/v1/walletslive · after account activation

Registering a watch-only wallet

Register an extended public key (mode: "xpub") for a network that the registry lists as usable in your environment. A network that is not usable is refused with network_unavailable.

{
  "store_id": "store_01J…",
  "network_id": "bitcoin:mainnet",
  "label": "Treasury (watch-only)",
  "mode": "xpub",
  "xpub": "zpub…",
  "gap_limit": 20
}

• Bitcoin: a BIP84 account key (xpub/zpub), giving native SegWit (p2wpkh) addresses.
• EVM / TRON: the account-level key (m/44'/60'/0' or m/44'/195'/0'), giving one address per intent.

One active wallet per store, network and environment keeps routing deterministic. The extended key is encrypted at rest and never returned by the API — responses show only its fingerprint and the derivation template.

Gap limit

Wallet software stops scanning after a run of unused addresses (the gap limit, default 20 here). Each payment intent reserves the next index, so many abandoned checkouts can exceed your wallet’s gap limit. The wallet object exposes next_index, gap_limit and last_used_index; when the unused run approaches the limit you are alerted so you can raise the gap limit in your wallet software. Addresses are never reused across intents.

Ownership proofs

To show that you control a registered key, sign a challenge with the key at derivation index 0:

1. POST /v1/wallets/{id}/ownership-challenge returns message, address, method (eip191 for EVM, bip137 for Bitcoin) and expires_at.
2. Sign message in your wallet.
3. POST /v1/wallets/{id}/ownership-proof with { "signature": "…" }.

Disabling

POST /v1/wallets/{id}/disable stops new derivations. Addresses already handed to customers stay watched until their window closes, so late payments are still observed and reported.