Sellback
Let the current prize holder accept a time-limited offer from your storefront.
Use the wallet session and the wallet API base URL ending in /api/v1/redeem. Your partner API key cannot authorize a holder's NFT transfer.
Show the offer
Call GET /buybacks. Match data.offers[].prize_id to the prize. Offer Sell back only when available is true and expires_at is in the future. Show amount_usd and the deadline before asking for confirmation. The server rechecks the offer when preparing it.
An offer may include operation_id and status: resume an existing awaiting_signature or processing operation instead of starting another. A loading error must not be presented as an expired offer.
Prepare, sign, submit
- Call
POST /prizes/{prizeId}/sellback/prepareand save the returneddata.idbefore opening the wallet. - If
statusisawaiting_signature, decode the base64transactionand ask the holder to sign only. Verify the wallet did not change the transaction message. - Save the signed bytes against this operation. Submit their base64 value as
signedTransactiontoPOST /sellbacks/{id}/submit. - Poll
GET /sellbacks/{id}with backoff. Onlycompletedconfirms the NFT return and payout. Then refresh the collection, offers and balances.
Do not broadcast the prepared transaction from your app. Verity submits it after receiving the holder's signature. The NFT return and USDC payout happen in one transaction; Verity pays the network fee.
Handle interruptions
| Situation | Action |
|---|---|
| Buyer rejects wallet approval | Keep the operation available to resume or cancel |
| Submit times out | Query the same operation; keep saved signed bytes for retrying the same submit |
processing | Show progress and keep polling; do not prepare a replacement |
| Unsigned approval expires | Read the operation again; prepare anew only after failed and while the offer is still available |
| Buyer changes their mind before signing | Cancel with POST /sellbacks/{id}/cancel |
| Already submitted | Track the existing operation; cancellation is unavailable |
Disable shipping for this item while sellback approval or confirmation is pending. Never interpret a timeout as a failed transfer. Reauthenticate an expired wallet session and resume the same operation ID.
The older partner API-key buyback endpoint and its availability fields do not implement this owner-signed flow. Use wallet offers for new integrations.
Next: Launch checks for sellback.