Generate a team badge

POST

/api/onboarding/generate-badge

const url = 'https://foxleague.ai/api/onboarding/generate-badge';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"payment_tx_hash":"example","team_name":"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/onboarding/generate-badge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "payment_tx_hash": "example", "team_name": "example" }'

Draws a team badge from the team name, stores it on IPFS and answers its ipfs:// address. Save it with POST /api/teams/badge or send it with POST /api/register.

Before your team exists every generation is free, within the budget in the rate limit below. Once it exists, a set number of regenerations is free (3 by default) and each further one costs FOXSY (1,000 by default). When a regeneration must be paid, the answer is success: false with data.payment_required: true and the price in data.cost_foxsy. Pay that amount to the players contract as a shop payment, then call again with the payment’s hash in payment_tx_hash.

Who: a signed-in player.

Rate limit: 3 generations per 10 minutes per wallet. A paid regeneration has its own allowance of 3 tries per payment in the same window. Before its team exists a wallet has 5 free badges in all and all wallets together have 300 a UTC day (the defaults).

Refusals:

Team name must be 1-15 characters: the trimmed name is empty or longer than 15 characters.
Team name can only contain letters, numbers, spaces and hyphens: the name holds another character (apostrophes are accepted too).
Badge generation is not available right now. Please try again later.: badges cannot be drawn right now.
Badge service temporarily unavailable. Please retry.: your team could not be read. Try again.
You've used your <free> free badge regenerations. The next one costs <cost> FOXSY.: the next regeneration must be paid. data carries the price.
Payment record check failed. Your payment is kept: please try again in a moment.: the payment records could not be read. Try again with the same hash.
The chain cannot be read right now. Your payment is kept: please try again in a moment.: the chain cannot be read right now. Try again with the same hash.
Chain is temporarily unavailable. Please retry shortly.: the chain cannot be reached right now. Try again with the same hash.
Could not confirm your payment on chain yet. Please try again in a moment.: the payment is not final yet. Try again with the same hash.
Your payment isn't confirmed on chain yet, but it may still settle. Please retry the badge regeneration in a moment.: the payment is still pending. Try again with the same hash.
Transaction <status> on chain: cannot confirm badge regeneration: the payment failed on chain.
Transaction was rejected on chain (<reason>) and refunded: badge regeneration not confirmed: the contract rejected the payment and returned it.
Transaction sender does not match your wallet: the payment was sent by another wallet.
Transaction was not sent to the badge regeneration contract: the payment went to another address.
Transaction is not a badge regeneration call: the transaction is not a shop payment.
Transaction did not pay in FOXSY: badge regeneration not confirmed: the payment used another token.
Payment (<paid> FOXSY) is less than required (<cost> FOXSY): the payment is too small.
Payment must be exactly <cost> FOXSY.: the payment is not exactly the price. Support returns it.
This payment was already used for a shop purchase.: the payment paid for a shop item.
This payment was already refunded and cannot be reused.: the payment was returned to you.
This payment was already used for a badge regeneration.: the payment already paid for a badge.
Our support team is handling this payment and will return it to you, so it cannot be used here.: support is returning this payment.
You have used your <n> free badge tries. Keep the badge you have or continue without one: you can make a badge later in Settings.: this wallet has drawn all its free badges before its team exists.
Badge generation is busy right now. Please try again later.: the free badges of the UTC day are used up for all wallets.
Too many badge generation requests. Please wait a few minutes.: the rate limit is reached.
Image generation failed. Your payment is kept: please try again in a moment.: the image could not be drawn.
Image processing failed. Your payment is kept: please try again in a moment.: the image could not be read.
Badge upload failed. Your payment is kept: please try again in a moment.: the badge could not be stored. This attempt does not count toward the rate limit.
We could not record your badge payment just now. Nothing was taken twice: please try again in a moment with the same payment.: the badge was drawn but the payment could not be recorded, so the badge is not delivered. Try again with the same hash.

When a paid regeneration fails in a way that leaves the payment unused, the answer carries code: "tx_pending": keep the transaction hash and call again with the same hash. Never pay twice.

Authorizations

session

Request Body^required

application/json

The team name to draw a badge for, with the payment of a paid regeneration.

object

payment_tx_hash

Only for a paid regeneration: the hash of your FOXSY payment, 64 hexadecimal characters. Omit it otherwise.

string | null

team_name

required

The team name the badge is drawn for: 1 to 15 characters among letters, numbers, spaces, hyphens and apostrophes.

string

Example ^generated

{
  "payment_tx_hash": "example",
  "team_name": "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

badge_ipfs_uri

Success answer: the badge address, ipfs://<cid>.

string

cost_foxsy

Payment answer: the price of the regeneration in whole FOXSY.

integer format: int64

free_regens

Payment answer: free regenerations a team gets.

integer format: int32

payment_required

Payment answer (success: false): always true. The next regeneration must be paid.

boolean

regen_count

Payment answer: regenerations your team has used.

integer format: int32

regenerations_max

Success answer: free regenerations a team gets.

integer format: int32

regenerations_used

Success answer: regenerations your team has used, including this one; null for a badge drawn before the team exists.

integer format: int32

team_name

Success answer: the team name the badge was drawn for.

string

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": {
    "badge_ipfs_uri": "ipfs://bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly",
    "regenerations_max": 3,
    "regenerations_used": 1,
    "team_name": "Fox Rovers"
  },
  "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

Generate a team badge

Authorizations

Request Body required

Example generated

Responses

200

Example

401

Example

Request Body^required

Example ^generated