Confirm a paid transfer lock waiver

POST

/api/shop/waive-cooldown

const url = 'https://foxleague.ai/api/shop/waive-cooldown';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"days":1,"player_nonce":1,"tx_hash":"example","wallet_address":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://foxleague.ai/api/shop/waive-cooldown \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "days": 1, "player_nonce": 1, "tx_hash": "example", "wallet_address": "example" }'

Applies a transfer lock waiver after you paid for it with shopPay on the game contract, in FOXSY. The server prices the waiver again when you confirm and the payment must equal that cost, so confirm soon after the quote. The card’s lock then ends floor_hours from now. With days (the number you asked the quote for) the payment buys that many days and the lock ends that many days earlier, never inside the floor.

Who: a signed-in player; wallet_address must be the session wallet and the payment must come from it.

Refusals:

Wallet mismatch: sign with the correct wallet: wallet_address is not the session wallet.
The chain cannot be read right now. Your payment is kept: confirm again in a moment. (tx_pending): the chain cannot be read right now.
Chain is temporarily unavailable. Please retry shortly. (tx_pending): the server cannot read the chain right now.
Transaction already processed: this transaction already delivered a purchase.
This payment was already refunded and cannot be used for a purchase.: this transaction was refunded.
This payment is being refunded: the money has not been returned yet. It cannot be used for a purchase; if it does not arrive, contact support.: the refund of this transaction was claimed and has not landed yet.
This transaction was already used for a badge regeneration.: this transaction paid a badge regeneration.
Our support team is handling this payment and will return it to you, so it cannot be used here.: our support team holds this payment.
Could not verify the payment state right now. Please retry in a moment. (tx_pending).
That player is not in your wallet.<refund note>: the card is not in your wallet.
This player has no active transfer cooldown.<refund note>: the card has no transfer lock.
This player is already within the un-waivable <h>h floor.<refund note>: what is left of the lock is at most the floor.
This player moved to your wallet before reaching its match gate. Its lock gets shorter with each match waiver bought for it; Reduce Cooldown does not apply.<refund note>: the card was sent before it reached its rarity’s match gate.
Choose from 1 to <n> days for this player.<refund note>: days is no longer between 1 and the days left above the floor.
Could not verify transaction yet. Please confirm again in a moment. (tx_pending): the transaction could not be read in time.
Transaction <status> on chain: cannot confirm cooldown waiver: the transaction failed on chain.
Your payment isn't confirmed on chain yet, but it may still settle. Please retry the cooldown waiver in a moment. (tx_pending): the transaction is not final yet.
Transaction was rejected on chain (<reason>) and refunded: cooldown waiver not confirmed: the call reverted on chain.
Transaction sender does not match your wallet: another wallet sent it.
Transaction was not sent to the cooldown waiver contract: it went to another contract.
Transaction is not a cooldown waiver call: it is not a shopPay call.
Transaction did not pay in FOXSY: cooldown waiver not confirmed: it paid another token.
Payment (<paid> FOXSY) is less than required (<cost> FOXSY)<refund note>: you paid less than the cost.
Transaction paid <paid> but the waiver costs <cost> FOXSY.<refund note>: you paid more than the cost; <paid> reads like 150 FOXSY.
Failed to record purchase. Your payment is kept: confirm again in a moment. (tx_pending).
Payment verified but applying the waiver failed. Your payment is kept: confirm again in a moment. (tx_pending).
This transaction was already processed for a cooldown waiver.: another confirm of the same transaction was applied first.
This player is no longer in your wallet, so the waiver was not applied.<refund note>: the card left your wallet before the waiver was applied.

A failed read while the waiver is priced again answers the generic failure with code: "tx_pending" too.

Refusals ending in <refund note> add one of these sentences (nothing when no payment can be refunded): Your payment is being refunded automatically. / Your refund has been queued and will be issued by our team. / This payment was already applied to a completed purchase, so no refund is needed. / This payment was already used for a badge regeneration, so no refund is needed. / Our support team is handling this payment and will return it to you. / The automatic refund could not be issued. Our team has been notified and will return your payment.

Refusals marked (tx_pending) carry code: "tx_pending": the payment was not refused, it could not be checked or recorded yet. Keep the transaction hash and confirm again with the same hash; never pay twice.

Authorizations

session

Request Body^required

application/json

A paid transfer lock waiver to confirm.

object

days

Optional: the days the payment bought, the same days you asked the quote for. Without it the waiver buys every started day above the floor.

integer | null format: int64

player_nonce

required

The NFT nonce of the card whose lock to cut.

integer format: int64

tx_hash

required

The hash of your shopPay transaction, 64 hexadecimal characters.

string

wallet_address

required

Your wallet; it must be the session wallet.

string

Example ^generated

{
  "days": 1,
  "player_nonce": 1,
  "tx_hash": "example",
  "wallet_address": "example"
}

Responses

200

Success or a refusal: read success (the refusals are in the description).

application/json

object

code

A machine-readable reason next to error, set only where the caller must act differently. tx_pending: the payment was not refused but could not be verified yet; keep the transaction hash and confirm again with the same hash, never pay twice.

string | null

data

The answer. Present when success is true.

object

cost_foxsy

required

FOXSY paid.

integer format: int64

days_paid

required

Days of the lock the payment bought.

integer format: int64

player_nonce

required

The card’s NFT nonce.

integer format: int64

remaining_hours

required

Hours left in the card’s transfer lock now.

integer format: int32

error

Why the request was refused, in plain words. Present when success is false.

string | null

success

required

true when the request did what it asked. false is a refusal: read error.

boolean

Example

{
  "data": {
    "cost_foxsy": 900,
    "days_paid": 9,
    "player_nonce": 3990,
    "remaining_hours": 72
  },
  "success": true
}

401

No valid session. The body is plain text: Missing Authorization header, Invalid Authorization format, Invalid session token or Session expired or invalid. Sign in again.

text/plain

string

Example

Session expired or invalid

422

The body does not match the request schema, for example a tx_hash that is not 64 hexadecimal characters. The body is plain text.

Confirm a paid transfer lock waiver

Authorizations

Request Body required

Example generated

Responses

200

Example

401

Example

422

Request Body^required

Example ^generated