On-chain

Connect an xpub

POST/api/v2/onchain/connect

Register an extended PUBLIC key so Trevi can hand out on-chain receiving addresses that pay the merchant directly. An xpub derives addresses and cannot sign — it confers no ability to spend.

Dashboard-only (merchant JWT). Rate limited to 10 attempts per 5 minutes.
This is the same position as NWC: the key that can move money stays with the merchant. Trevi only says where their money should land, and never gets to move it.
An xpub is public, so it is not stored encrypted. Losing one costs transaction privacy, not funds.
400 code: "invalid_format" or "wrong_network"; 422 code: "underivable" — the key parsed but no address could be derived from it; 503 code: "disabled" — on-chain receiving is switched off on this deployment.

Authentication

Requires a dashboard session JWT in the Authorization: Bearer … header.

Body parameters

xpubstringrequired

an extended PUBLIC key. Never a seed, mnemonic, or private key.

POST/api/v2/onchain/connect

curl --request POST "https://api.trevi.cash/api/v2/onchain/connect" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $TREVI_JWT" \
  --data '{ "xpub": "zpub6r…" }'

200Sample response

{
  "success": true,
  "connection": {
    "xpub": "zpub6r…",
    "fingerprint": "8f3a1c2b",
    "first_address": "bc1q…",
    "connected_at": "2026-08-13T12:00:00.000Z"
  }
}

Was this page helpful?

Check a receive invoice

On-chain connection status