Get pull status

Get the status of a pull by its requestId

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/pull/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/pull/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "requestId": "6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64",
  "buyerWalletAddress": "0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2",
  "packId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13",
  "nonce": "48210937465120938475",
  "numOfTokens": 1,
  "status": "PENDING_PAYMENT",
  "permitFundTxHash": null,
  "error": null,
  "result": null
}

GET

gacha

pull

status

Get the status of a pull by its requestId

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/pull/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/pull/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "requestId": "6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64",
  "buyerWalletAddress": "0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2",
  "packId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13",
  "nonce": "48210937465120938475",
  "numOfTokens": 1,
  "status": "PENDING_PAYMENT",
  "permitFundTxHash": null,
  "error": null,
  "result": null
}

Take requestId from the submission response or the stream’s pull_started event.
Poll about once per second until RESOLVED or FAILED. A confirmed payment can still be waiting for cards. It cannot subsequently become FAILED.
The pull stays in PENDING_PAYMENT while the API checks an uncertain payment or a previously used nonce or checkout. If this lasts more than ten minutes, stop polling and contact Renaiss with that ID before signing again.

A FAILED pull charged nothing. Resubmitting the same signed payload, including a copy already in flight, can restart it at PENDING_PAYMENT. You can look up the request for at least 30 days.

Request

Builder key required

Response

Failures after submission

If the HTTP 200 response has status: "FAILED", the buyer was never charged. Stop polling and use error.code to find the next step below.Most codes return Unable to fund the pull. in error.message. The table quotes the other messages where they apply.

Code	`error.message` and recovery
`FUNCTION_ERROR` `GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET` `GACHA_V3_SUB_PACK_LINEUP_LOAD_FAILED` `GACHA_V3_OPEN_PACK_CHECKOUT_BUDGET_ERROR` `GACHA_V3_MERKLE_ROOT_CHECK_FAILED`	`Unable to fund the pull.` If this persists, contact Renaiss with `x-request-id`.
`CARD_PACK_NOT_ACTIVE`	Show the pack as unavailable.
`CARD_PACK_NOT_FOUND`	The pack does not exist. Stop retrying this pack ID.
`CONTRACT_REVERT`	A `FAILED` status confirms this pull was unpaid. Check the wallet balance and allowance before another attempt.
`CONTRACT_WALLET_CANNOT_RECEIVE_NFT`	Use a wallet that can receive the collectible.
`EOA_PURCHASE_REJECTED`	`Permit deadline must be within the next five minutes` Prepare a new pull with a valid deadline.
`GACHA_V3_NOT_ENOUGH_CARDS_IN_SET`	Request fewer collectibles or wait.
`GACHA_V3_NO_SELLABLE_LINEUP`	Try again when the pack is available.
`GACHA_V3_PRICE_MISMATCH`	Read the new price, then prepare and sign again.
`INSUFFICIENT_ALLOWANCE`	Approve at least `approval.requiredAmount` of USDT for `approval.spender` from the prepare response. Resend the signed pull before it expires.
`INSUFFICIENT_USDT_AMOUNT`	Top up the wallet’s USDT balance. Resend the same signed pull before it expires, or prepare a new one.
`OP_WALLET_BUSY`	`Payments are busy right now and nothing was charged. Please try again in a few seconds.` If the signature is still valid, resend the same signed request. Otherwise, prepare a new one.
`PERMIT_DEADLINE_TOO_FAR`	Prepare again and use the new deadline.
`PERMIT_EXPIRED`	Prepare and sign a fresh permit after checking payment status.
`PULL_NOT_STARTED`	`The connection closed before the pull started. Nothing was charged. Send the same signed pull again.`
`WRONG_REQUEST_PARAMS`	Use an eligible buyer wallet and prepare the pull again.

For an unrecognized code, check the wallet’s pull history before signing again.On mainnet, a refused USDT transfer can still return INSUFFICIENT_USDT_AMOUNT when the allowance is short. Check both the balance and the USDT allowance for Permit2. On testnet, INSUFFICIENT_ALLOWANCE identifies a short approval when the balance covers the price.

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`, `FUNCTION_ERROR`, or another code	`error`	`Internal server error` Retry the status lookup later with the same `requestId`.

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_PAYMENT — The API accepted the pull and is processing the payment.
PENDING_RESOLUTION — Payment is confirmed and the API is assigning cards. The status can no longer change to FAILED.
RESOLVED — The pull is complete. Read result.draws for the cards.
FAILED — The buyer was never charged. Read error.code for the reason.

Available options:

PENDING_PAYMENT,

PENDING_RESOLUTION,

RESOLVED,

FAILED

buyerWalletAddress

string

required

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

packId

string<uuid>

required

nonce

string

required

numOfTokens

integer

required

permitFundTxHash

string | null

required

The funding transaction hash. Null until payment is confirmed.

error

object | null

required

Contains code and message when status is FAILED. Null for all other statuses. See pull failures and recovery.

Show child attributes

result

object · null · null

required

The same body as GET /v2/gacha/draw-status for this pull. Null unless the status is RESOLVED.

Show child attributes

Getting started

Gacha

Marketplace

Wallet collections

Redeem and shipping

Developer resources

Partner integrations

Get pull status

Request

Response

Failures after submission

Error codes

Authorizations

Query Parameters

Response