Get buyback status

Get the status of a buyback by its requestId

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/buyback/status \
  --header 'x-builder-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-builder-api-key': '<api-key>'}};

fetch('https://api.renaiss.xyz/v2/gacha/buyback/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "requestId": "b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20",
  "buyerWalletAddress": "0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2",
  "cardPackId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13",
  "settlementIds": [
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "PENDING",
  "txHash": null,
  "totalAmountInUsdt": null,
  "itemCount": null,
  "error": null
}

GET

gacha

buyback

status

Get the status of a buyback by its requestId

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/buyback/status \
  --header 'x-builder-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-builder-api-key': '<api-key>'}};

fetch('https://api.renaiss.xyz/v2/gacha/buyback/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "requestId": "b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20",
  "buyerWalletAddress": "0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2",
  "cardPackId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13",
  "settlementIds": [
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "PENDING",
  "txHash": null,
  "totalAmountInUsdt": null,
  "itemCount": null,
  "error": null
}

Poll about once per second until COMPLETED or FAILED. The request remains available for at least 30 days.If PENDING lasts more than ten minutes, stop polling and contact Renaiss with the original requestId. Wait for the outcome before signing another buyback for the same cards.

Request

Builder key required

Response

Failures after submission

If the HTTP 200 body has status: "FAILED", read error.code and error.message. A failed request bought nothing back. Refresh the wallet’s offers before signing a replacement. If it stays PENDING for more than 10 minutes, stop polling and contact Renaiss with the original requestId. Braces in the table mark runtime values.

Code	`error.message`
`GACHA_V3_BUYBACK_SNAPSHOT_NOT_FOUND` `GACHA_V3_SETTLEMENT_ID_MISMATCH` `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND` `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND`	`Internal server error` Contact Renaiss with the original `requestId`.
`CONTRACT_REVERT`	`Smart contract execution reverted` `Contract error: {reason}`
`GACHA_V3_BUYBACK_EXPIRED`	`Buyback has expired for {buybackId}`
`GACHA_V3_BUYBACK_PRICE_CHANGED`	`amount {signedAmount} does not match expected total {expectedTotal}`
`GACHA_V3_BUYBACK_VERIFY_FAILED`	`Buyer does not own this card`
`GACHA_V3_DRAW_RECORD_NOT_FOUND`	`Pack draw record not found for buybackId {buybackId}`
`GACHA_V3_TOKEN_STATUS_INVALID`	`Card is already buyback or released`
`OP_WALLET_BUSY`	`Payments are busy right now and nothing was charged. Please try again in a few seconds.` Wait a few seconds, then resend the same signed buyback.
`PERPETUAL_GACHA_PACK_NOT_FOUND`	`Perpetual VRF pack not found: {cardPackId}`
`PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`	`Buyback token must be USDT`

Error codes

Match the HTTP status and response text to a row below. For guidance on codes shared across endpoints, see Error meanings and recovery.

HTTP	Error code	Text field	Response text and recovery
`400`	`WRONG_REQUEST_PARAMS`	`message`	`Bad request - invalid parameters` A field is missing or has the wrong form. Fix the request and send it again.
`401`	`API_AUTH_INVALID_CREDENTIAL`	`error`	`Invalid authentication credential` The builder key is malformed, unknown, expired or revoked. Check the key. Do not retry with the same key.
`401`	`API_AUTH_MISSING_CREDENTIAL`	`error`	`Required authentication credential is missing` No builder key was sent. Send your builder key in the `x-builder-api-key` header.
`403`	`API_AUTH_CREDENTIAL_NOT_ALLOWED`	`error`	`Credential is not allowed by this policy` This route takes a builder key only. Remove the `Authorization` header and any other credential, then send the request again.
`403`	`GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API`	`error`	`This builder checks out on its own surface, not on the public API` This builder key cannot be used on this API. Do not retry; contact Renaiss.
`404`	`REQUEST_NOT_FOUND`	`error`	`Request not found` The request id is unknown, was made with another builder key, or is a request of the other kind. Check the id returned by the `POST` that created it.
`429`	`API_AUTH_RATE_LIMITED`	`error`	`Authentication rate limit exceeded` The builder key hit its rate limit. Wait a little, then retry at a lower rate.
`500`	`API_AUTH_ERROR`	`error`	`Internal server error`
`500`	`FUNCTION_ERROR`	`error`	`Internal server error`
`500`	Other code	`error`	`Internal server error`

Authorizations

x-builder-api-key

string

header

required

Your approved builder API key. Keep it on your backend. Gacha and marketplace writes also require wallet action signatures. Redeem also needs a wallet access token, a Bearer token the API issues after the wallet signs a sign-in message.

Query Parameters

requestId

string<uuid>

required

Response

Success

requestId

string<uuid>

required

status

enum<string>

required

PENDING: in progress. COMPLETED: settled on chain. FAILED: nothing was bought back.

Available options:

PENDING,

COMPLETED,

FAILED

buyerWalletAddress

string

required

20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum.

cardPackId

string<uuid>

required

settlementIds

string[]

required

32 bytes encoded as 0x followed by 64 hexadecimal digits.

txHash

string | null

required

The buyback transaction hash. Null unless COMPLETED.

totalAmountInUsdt

string | null

required

USDT paid, with 18 decimals. Null unless COMPLETED.

Pattern: ^\d+$

itemCount

integer | null

required

How many collectibles were bought back. Null unless COMPLETED.

error

object | null

required

Why the request failed: { code, message }. Null unless the status is FAILED. A FAILED buyback bought nothing back. The codes and sentences are those of POST /v2/gacha/buyback. The code is a plain string, so new codes can appear. What to do for each:

PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED: the signed token is not USDT. Prepare the buyback again from the offers list.
GACHA_V3_TOKEN_STATUS_INVALID: a collectible in the request was already sold back or sent to the wallet. Read GET /v2/gacha/buyback/offers and sign again for the collectibles that are still offered.
GACHA_V3_BUYBACK_VERIFY_FAILED: the wallet does not own a collectible in the request. Read GET /v2/gacha/buyback/offers and sign only the collectibles it returns.
GACHA_V3_BUYBACK_EXPIRED: no tier pays for a collectible now (window closed or a zero-percent hold). Read GET /v2/gacha/buyback/offers again and retry only the collectibles it returns.
CONTRACT_REVERT: the buyback was rejected. Read GET /v2/gacha/buyback/offers to see which collectibles are still offered, then sign again.
PERPETUAL_GACHA_PACK_NOT_FOUND: the pack could not be found. Refresh the offers and check the pack ID.
GACHA_V3_DRAW_RECORD_NOT_FOUND: a settlement ID could not be found for this pack. Refresh the offers and sign only the settlement IDs returned for that pack.
GACHA_V3_BUYBACK_PRICE_CHANGED: the signed amount is not the price now: a buyback tier ended after you read the offers. Read GET /v2/gacha/buyback/offers again and sign the new amount.
OP_WALLET_BUSY: every payment sender is busy. Retry the request. Send the same signed buyback again after a few seconds.
Any other code: read GET /v2/gacha/buyback/offers before you send the request again. A buyback whose transaction may already have been sent (for example a confirmation that timed out, or a rejection at the send) is not marked FAILED: it stays PENDING until it is reconciled.

Show child attributes

Getting started

Gacha

Marketplace

Wallet collections

Redeem and shipping

Developer resources

Partner integrations

Get buyback status

Request

Response

Failures after submission

Error codes

Authorizations

Query Parameters

Response