<aside> 💡 If you have any feature requests or issues with the API, please join our Discord here and go to the #developers channel!


ℹ️ Info

🏖️ Sandbox (for testing & development)

Network: Mumbai

Website URL: https://sandbox.mintkudos.xyz

API Endpoint: [<https://sandbox-api.mintkudos.xyz>](<https://sandbox-api.mintkudos.xyz>)

OpenSea Collection: https://testnets.opensea.io/collection/mintkudos-sandbox

Chain ID: 80001 (necessary when signing the token creation message)

Verifying Contract: 0xB876baF8F69cD35fb96A17a599b070FBdD18A6a1

🎉 Production (once you’re ready)

Network: Polygon

Website URL: https://mintkudos.xyz

API Endpoint: [<https://api.mintkudos.xyz>](<https://api.mintkudos.xyz>)

OpenSea Collection: https://opensea.io/collection/mintkudos

Chain ID: 137 (necessary when signing the token creation message)

Verifying Contract: 0x60576A64851C5B42e8c57E3E4A5cF3CF4eEb2ED6

🎉 Tokens API

<aside> 💡 API endpoint designed to return information pertaining to Kudos tokens.




💳 Wallets API

<aside> 💡 API endpoint designed to return information pertaining to wallets (which are Ethereum-based accounts).




👨‍👩‍👧‍👧 Communities API

<aside> 💡 API endpoint designed to return information pertaining to communities.




<aside> 💡 Endpoints with an * requires an API key along with the community ID associated with your community. Instructions on how to use the API key is below. Please shoot us a message on Discord if you’re interested in using this endpoint. In the future we plan to make this self-serve through a developer portal.


📃 Pagination

All methods in the API accept limit and offset parameters for fetching specific subsets of results from the API. offset starts at and defaults to 0, limit can be any value between 0 and 1000, and defaults to 50. If limit in the request query is greater than the maximum allowed value (1000), the API will assume the maximum allowed value as the limit instead.

Fetching All Results

If your application needs to fetch all the items that match a specific criteria, the API returns a limit property. An application can use this property to determine whether to continue fetching results if the number of items in the data property is equal to the limit value. If the number of items in the data property is less than the limit value, it can be assumed that you have reached the end of available items.

🔑 API Key

You may have noticed that some API calls, such as the /v1/communities/:communityId endpoints and the POST /v1/tokens endpoint, require an API key. As we are still a developing product & team, we want to make sure that we can iterate with our valued partners & users. To ensure that we can provide the best experience & support possible, we are not providing the API key openly. Please contact us through the #developers channel on our Discord channel if you would like to obtain an API key with your use case for how you want to use the auth-gated API calls.

If you already have an API key from us, thank you for using our APIs to build on top of the Kudos ecosystem. You are a valued partner :)

How to use the API key

The API key is used to make calls that are auth-gated. We leverage Basic Auth. Follow these steps to make sure that your API calls are properly authenticated:

  1. Obtain the communityId and API Key from us (note that you will use the same communityId in the /v1/communites/:communityId endpoints)
  2. Combine the communityId and API Key with a colon and then base64 encode the string
  3. Attach the encoded string to the Authorization field of the API request’s header. Don’t forget the word Basic in front of the encoded string!
  4. Make the call 🪄

🔃 Async Endpoint

Some API endpoints are what we consider to be an async endpoint, which means the initial call doesn’t return the results of the operation. We provide this capability for endpoints that require a blockchain network call, because sometimes a blockchain call can take much longer than expected due to network congestion or other reasons.

In these cases, if we offered a synchronous endpoint, the request may have to remain open and blocking for much longer than normal, or it may just time out. To prevent this from happening, we submit the transaction to the blockchain and immediately return to you the operation ID, which you can use to poll against our operations API endpoint to get the results. This is largely inspired by Azure’s Asynchronous Request-Reply pattern.

How do we return the operation ID?

Once we successfully receive your request for an async operation (such as creating a new Kudos token), we will return the call with a 202 Created status code.

In the header of the response, we will leave the location of the operation object in the Location header, like this:

// response header
Location: /v1/operations/dc3a7730-53e2-4af6-acc9-d13b2fcf10e2

How do you use the operation ID?

The operations API consists of one endpoint - the GET operation endpoint - which returns the status of a given operation.



We recommend that you poll against the operations endpoint with the particular ID until the endpoint returns a terminal status (success or error). Currently we don’t return a Retry-After header but in the future we may. We recommend waiting at least 1 second before querying the endpoint again.