Submit a pull

Submit a signed pull and poll its requestId

curl --request POST \
  --url https://api.renaiss.xyz/v2/gacha/pull/request \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "numOfTokens": 5,
  "amountPerToken": "<string>",
  "nonce": "<string>",
  "deadline": 123,
  "buyerWalletAddress": "<string>",
  "permitSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    packId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    numOfTokens: 5,
    amountPerToken: '<string>',
    nonce: '<string>',
    deadline: 123,
    buyerWalletAddress: '<string>',
    permitSignature: '<string>'
  })
};

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

import requests

url = "https://api.renaiss.xyz/v2/gacha/pull/request"

payload = {
    "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "numOfTokens": 5,
    "amountPerToken": "<string>",
    "nonce": "<string>",
    "deadline": 123,
    "buyerWalletAddress": "<string>",
    "permitSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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
}

POST

gacha

pull

request

Submit a signed pull and poll its requestId

curl --request POST \
  --url https://api.renaiss.xyz/v2/gacha/pull/request \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "numOfTokens": 5,
  "amountPerToken": "<string>",
  "nonce": "<string>",
  "deadline": 123,
  "buyerWalletAddress": "<string>",
  "permitSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    packId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    numOfTokens: 5,
    amountPerToken: '<string>',
    nonce: '<string>',
    deadline: 123,
    buyerWalletAddress: '<string>',
    permitSignature: '<string>'
  })
};

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

import requests

url = "https://api.renaiss.xyz/v2/gacha/pull/request"

payload = {
    "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "numOfTokens": 5,
    "amountPerToken": "<string>",
    "nonce": "<string>",
    "deadline": 123,
    "buyerWalletAddress": "<string>",
    "permitSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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
}

Submit and track a pull

Sign the purchase. Have the buyer sign the full Permit2 payload from Prepare a pull. Send it with your builder key. The streaming endpoint accepts the same body and checks the same signature.
Save the request ID. The API returns HTTP 202 with requestId and the current status. The purchase belongs to this builder and buyer wallet.
Check the result. Use the ID to get pull status about once per second. Stop at RESOLVED or FAILED.

If you lose the response, resend the same signed payload to recover the same requestId. A failed request can restart. The same signature can charge the buyer only once.If the pull stays in PENDING_PAYMENT for more than 10 minutes, stop polling and contact Renaiss with the original requestId before signing again.

Request

Builder key and wallet signature

Response

Failures after submission

A new submission returns HTTP 202 with PENDING_PAYMENT. Resubmitting the same signed pull can restart a failed attempt. To check an existing request without restarting it, poll its requestId. A recorded FAILED means nothing was charged.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

For HTTP 4xx or 5xx, match the status and response text below. For guidance on codes shared across endpoints, see Error meanings and recovery.

HTTP	Error code	Text field	Response text and recovery
`400`	`API_AUTH_INVALID_INPUT`	`error`	`Request body is too large` The request body exceeds 16 KiB. Send a smaller body.
`400` `404`	`EOA_PURCHASE_REJECTED`	`error`	400 · `SAFE addresses are not supported by v2` Use a different buyer wallet. 404 · `Pack not found` Choose an available pack ID from List packs.
`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.
`400`	No code	`text/plain`	`Malformed JSON in request body`
`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`	`API_AUTH_INVALID_ACTION`	`error`	`Invalid wallet action proof` The signature was not accepted for the wallet and the prepared data, or the deadline has passed. Prepare again and sign the new data. For a contract wallet, its `isValidSignature` must return `0x1626ba7e` for the EIP-712 digest of the prepared data.
`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.
`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` Signature verification can fail if the API cannot read the chain. Retry later with the same signed payload to recover the original request.
`500`	`CARD_PACKS_QUERY_FAILED`	`error`	`Internal server error` Read again after a short wait.

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.

Body

application/json

packId

string<uuid>

required

numOfTokens

integer

required

Required range: 1 <= x <= 10

amountPerToken

string

required

Pattern: ^\d+$

nonce

string

required

Pattern: ^\d+$

deadline

integer

required

buyerWalletAddress

string

required

permitSignature

string

required

Signature over the typed data that prepare returned, as hex of at most 4,096 bytes. An EOA signs the typed data. A contract wallet submits what its isValidSignature accepts for that data's EIP-712 digest, which can be empty (0x); Permit2 is the caller. The signature is checked before payment and again on chain.

Response

The pull was accepted. The body is the pull status.

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

Submit and track a pull

Request

Response

Failures after submission

Error codes

Authorizations

Body

Response