Claims

Claim cashback

POST/api/v2/claim/:token

The customer names any Lightning address and the merchant's wallet pays it — one hop, no intermediary. Receiving cashback requires nothing but a Lightning address.

Success responds { success: true, amount_sats, message }.
Failures respond { success: false, error, code } — the human-readable text is on error, NOT on message. Check code programmatically.
400 code: "invalid_address" — the Lightning address was missing or unusable.
404 code: "not_found" — the token is unknown or already spent.
409 code: "expired" — the 30-day claim window has passed; the reservation has been released and nothing will be sent.
409 code: "payout_failed" — the merchant's wallet could not complete the payment. Nothing was taken from the customer, because they never had anything to take; the reservation stands and Trevi retries it in the background.
Rate limited to 30 requests per 15 minutes per IP.
Firing this against the live API moves real satoshis out of a merchant's wallet.

Authentication

No authentication required.

Path parameters

tokenstringrequired

the one-time token from the claim link

Body parameters

lightning_addressstringrequired

any Lightning address — the customer picks their own wallet

POST/api/v2/claim/:token

curl --request POST "https://api.trevi.cash/api/v2/claim/CLAIM_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "lightning_address": "alice@getalby.com" }'

200Sample response

{
  "success": true,
  "amount_sats": 4500,
  "message": "Sent. The sats are on their way to your wallet."
}

Was this page helpful?

View a cashback claim

Get connection parameters