🔐

[Async] POST /tokens

Asynchronously create a new Kudos token

Caveat

  • This endpoint requires an API key. Refer to the Authentication doc for more info.
  • This endpoint also is an asynchronous endpoint, which means the initial call does not return the response immediately. Please refer to the Async Endpoint doc for more information about how to use these APIs.

Body

Field
Type
Description
Optional?
creator
address
The ETH address of the creator of the Kudos token.
false
headline
string
Headline of kudos provided by creator during token registration.
false
description
string?
Description of kudos provided by creator during token registration.
Validation: 0 ≤ length ≤ 1000
true
startDateTimestamp
number?
Start date of kudos in UTC timestamp format (milliseconds), provided by creator during token registration.
true
endDateTimestamp
number?
End date of kudos in UTC timestamp format (milliseconds), provided by creator during token registration.
true
links
string[]?
List of links, part of token metadata.
true
communityId
string
Community identifier for Community object.
false
nftTypeId
string
ID of the NFT type that is attached to the created token. Check the GET /v1/communities/:communityId/nftTypes endpoint to see available options. Default values:
false
isSignatureRequired
boolean
Represents if a signature is required in order to claim the kudos token. Please see the Distribution methods section for more info.
false
isAllowlistRequired
boolean
Represents if checking claimee identifiers or address against an allowlist is required in order to claim the kudos token. Please see the Distribution methods section for more info.
false
contributors
string[]?
List of contributors that should be added to the allowlist of people who can claim the token. Only relevant if isAllowlistRequired=true
false if isAllowlistRequired=true, otherwise true
totalClaimCount
number?
Number of claims allowed for the token. Should be null isAllowlistRequired = true.
true if isAllowlistRequired=true, otherwise false
expirationTimestamp
number?
UTC timestamp format (milliseconds) for when the claim for the Kudos token should expire (ie. be invalidated).
true
customAttributes
CustomAttributeObject[]
A JSON array that dictates custom attributes that the user wishes to associate with the Kudos outside of the default fields above. Keywords like headline and isHidden are not allowed as the field name.
Each custom attribute object should be of the format: {"fieldName": "custom_attributes_1", "type": "string", "value": "value_1"}, where type should be string, number, date, boolean
true
signature
string
Signature that proves that the creator address signed the relevant information to create the Kudos token.
More info on how to generate the signature below.
false

How to generate the create Kudos token signature

What am I signing?

Using your Ethereum account’s private key, you are signing the fields of a new Kudos token that you are trying to create. This helps us make sure that the creator of the Kudos token is who they really say they are, and that the creator is definitely asking to create a Kudos token with the specific fields.

Signing with Ethers.js

If you're not using Ethers.js, your code may not look like this. We recommend using this wonderful library though!
const types = {
Kudos: [
{ name: "headline", type: "string" },
{ name: "description", type: "string" },
{ name: "startDateTimestamp", type: "uint256" },
{ name: "endDateTimestamp", type: "uint256" },
{ name: "links", type: "string[]" },
{ name: "communityUniqId", type: "string" }, // note that this is called communityUniqId and not communityId
{ name: "isSignatureRequired", type: "bool" },
{ name: "isAllowlistRequired", type: "bool" },
{ name: "totalClaimCount", type: "int256" },
{ name: "expirationTimestamp", type: "uint256" },
],
};
// The data to sign
const value = {
headline: headline, // mandatory
description: description || "", // optional but fallback should be empty string
startDateTimestamp: startDateTimestamp || 0, // optional but fallback should be 0
endDateTimestamp: endDateTimestamp || 0, // optional but fallback should be 0
links: links || [], // optional but fallback should be empty array
communityUniqId: communityId // mandatory
isSignatureRequired: isSignatureRequired, // mandatory
isAllowlistRequired: isAllowlistRequired, // mandatory
totalClaimCount: totalClaimCount || 0, // could be optional but fallback should be 0
expirationTimestamp: expirationTimestamp || 0 // optional but fallback should be 0
};
// Domain info (if you're using the sandbox environment)
const domainInfo = {
name: 'Kudos',
// Mumbai
chainId: 80001,
verifyingContract: "0xB876baF8F69cD35fb96A17a599b070FBdD18A6a1"
};
// Domain info (if you're using the production environment)
const domainInfo = {
name: 'Kudos',
// Polygon - comment this out if you're on Mumbai
chainId: 137,
verifyingContract: "0x60576A64851C5B42e8c57E3E4A5cF3CF4eEb2ED6"
};
// Get signer
const provider = new ethers.providers.JsonRpcProvider(/* constructor params */);
const signer = provider.getSigner(/* address */);
// Obtain signature
const signature: string = await signer._signTypedData(domainInfo, types, value);

Example Response

// status
202 Created
// header
Location: /v1/operations/dc3a7730-53e2-4af6-acc9-d13b2fcf10e2
// body
{}

Scenario 1: Allowlisted Kudos

The below body when feeding it to the POST /v1/tokens endpoint will result in the creation of a Kudos token that is allowlisted to the addresses in the contributors field:
{
"creator": "0xd8068f813c45C88CEBb02cBC0F91F95626Ec9a34",
"headline": "test",
"description": "description",
"startDateTimestamp": 797583600000,
"endDateTimestamp": 797670000000,
"links": [
"https://twitter.com/keikumata"
],
"communityId": "kudos",
"nftTypeId": "defaultGreenPurple",
"isSignatureRequired": true,
"isAllowlistRequired": true,
"contributors": ["0xc4A959AF92b73B3D783fA2569F1F9776d2136cE9"],
"expirationTimestamp": 1750576905000,
"customAttributes": [
{
"fieldName": "custom_attributes_1",
"type": "string",
"value": "value_1"
},
{
"fieldName": "custom_attributes_2",
"type": "number",
"value": 5
},
],
"signature": "0x6e869c042c6053d2ed88379ba04c433e6299aecaddf48a5f06f4268a77cc9307609182c26e9add5559010a4a2172007b80dc36aeda42cb781a949e8c435d191a1b"
}

Scenario 2: Not-allowlisted Kudos

The below body when feeding it to the POST /v1/tokens endpoint will result in the creation of a Kudos token that is claimable up to the totalClaimCount without the need to be allowlisted:
{
"creator": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
"headline": "headline",
"communityId": "kudos",
"nftTypeId": "defaultGreenPurple",
"isSignatureRequired": false,
"isAllowlistRequired": false,
"totalClaimCount": 5,
"signature": "0x857b6250d82b6f1bdcb908ac865d0dee7705f10a42506d24da77a7078dc6c8b3387c60db21816b9439146837cea39c1f7471ea321dcc6f33da4a8e425695e86e1b"
}