Docs

🎟️ Prize Draws

Suggest Edits

🚧

Beta Feature

Please note that this feature is currently in beta.

It might contain bugs or errors that could lead to unexpected behaviors. We highly recommend testing all beta features thoroughly in a controlled, non-production environment before deploying it into production.

We value your feedback. Should you encounter any problems or bugs, or if you have any suggestions for improvements, please report them in the Co:Create Discord.

Overview

Prize draws offer an exciting opportunity for users to engage with your application and stand a chance to collect exciting prizes. Community members can enter a prize draw by purchasing a specific count of tickets using their platform-issued ERC20 tokens held in their Co:Create wallet. At a time determined by you, the lucky winner is chosen and the prize is distributed to them.

This Prize Draws API boosts user engagement and also introduces an exciting way to distribute desirable products & services to your community.

Use Cases

  • Web3 Projects: Web3 projects can leverage the Prize Draws API to organize exciting events where participants purchase tickets using ERC20 tokens for a chance to win exclusive digital collectibles in the form of NFTs.
  • Event Ticketing: Event organizers can use the Prize Draws API as a unique way to distribute tickets for VIP passes, backstage access, or premium seating, represented as NFTs.
  • E-commerce Platforms: Online shopping platforms can introduce prize draws as special promotional events, providin the chance to win exclusive merchandise, limited-time discounts, or even a shopping spree, all represented as NFTs.

How It Works

  1. Prize Draw Creation: As the prize draw organizer, you can create a prize draw and configure it by setting parameters such as ticket price, total tickets available, and the number of winners to be drawn.
  2. Ticket Sales: Once the prize draw is active, participants can purchase tickets using their ERC20 tokens. As tickets are purchased, the Co:Create platform keeps track, ensuring limits like maximum tickets per user are adhered to.
  3. Prize Drawing: After the purchase period ends and the prize draw is completed, a predetermined number of winners is selected from the pool of participating tickets. Winners are then automatically awarded their prizes.

📘

Note: Winning ticket data is available after the prize draw settles, not when it completes. The settlement phase includes randomly drawing winners and distributing prizes. For more information about prize draw phases, see Prize Draw State Management.

Using the Prize Draw API

At a simplified level, the Prize Draw API workflow is the following:

  1. Create a prize draw. Create the prize draw using:
    1. The payable token id (ERC-20)
    2. The receivable token id (ERC-721 or ERC-1155)
    3. The price per ticket, in the amount of ERC-20 tokens to be used to purchase 1 ticket
    4. Any other parameters you wish to set
  2. Sell tickets. Provide to the API:
    1. The prize draw id, provided in the response from Step 1
    2. The user's email
    3. The number of tickets to purchase using the specified ERC-20 tokens from their wallet
  3. Complete and settle Prize draw:
    1. Complete the prize draw to stop ticket sales. Completion can be performed automatically by specifying an end date during the initial configuration
    2. Settle the prize draw to pick winners and distribute the prize(s) to them. Settlement is performed automatically by default with the auto-settle flag set to true

Requirements

  1. You have created an ERC-20 token.
  2. You have created an ERC-721 or ERC-1155 token.

Note: Using Co:Create's Synchronous or Asynchronous APIs to create your token doesn't matter, so long as you have the token ids associated with the tokens you would like to configure the prize draw with.

Endpoints

The base URL for the Prize Draw API is https://api.testcocrt.xyz/alpha/prize-draws. For details regarding required and optional parameters for the prize draw please check out our Prize Draw API Reference.

EndpointTypeDescription
List Prize DrawsGET/prize-draw/
Retrieve a list of all prize draws.
Get Prize DrawGET/prize-draw/:prize_draw_id
Fetch detailed information about a specific prize draw using its unique identifier.
Create Prize DrawPOST/prize-draw
Create a new prize draw.
Update Prize DrawPATCH/prize-draw/:prize_draw_id
Modify details of an existing prize draw using its unique identifier. This can be executed only if a prize draw is in the "draft" state.
Pause Prize DrawPOST/prize-draw/:prize_draw_id/pause
Temporarily halt a prize draw, preventing further actions until resumed.
Cancel Prize DrawPOST/prize-draw/:prize_draw_id/cancel
Terminate a prize draw permanently. Prize draw cannot be resumed from this state.
Resume Prize DrawPOST/prize-draw/:prize_draw_id/resume
Restart a previously paused prize draw, allowing further actions.
Complete Prize DrawPOST/prize-draw/:prize_draw_id/complete
Finalize a prize draw, marking it as completed. Winners are not yet picked.
Settle Prize DrawPOST/prize-draw/:prize_draw_id/settle
Settle prize draw by picking winners and distributing prizes. Async endpoint.
List TicketsGET/prize-draw/:prize_draw_id/
Retrieve a list of all tickets associated with a specific prize draw.
Purchase TicketsPOST/prize-draw/:prize_draw_id/ticket
Purchase a new ticket for a specific prize draw.
Get TicketGET/prize-draw/:prize_draw_id/ticket/:prize_draw_ticket_id
Fetch detailed information about a specific ticket using its unique identifier within a prize draw.

Example - Prize Draw with ERC721 prize

The following example will walk through a Prize Draw workflow where the prize is an ERC-721:

  1. Creating a Prize Draw
  2. Selling tickets
  3. Completing a Prize Draw
  4. Checking the status of a specific ticket

Example - Prize Draw creation

Imagine an existing ERC20 token named TRAVEL_MILES, distributed among a community of travel enthusiasts of a specific airline. This token has an id labeled as d56a253a-7b04-41f0-9cd2-04318877afd2

The airline wishes to offer their community the opportunity to enter a prize draw using their TRAVEL_MILES tokens for a newly minted and exclusive NFT collection, GLOBAL_STATUS, which would provide the highest tier of loyalty program membership to the winners. The GLOBAL_STATUS collection is issued as an ERC721 token, has a Co:Create platform token id of 002b0807-48e1-43f5-8432-d018c6d0eadb.

The conditions for the prize draw are as follows:

  • Community members can purchase a single prize draw ticket for 100 TRAVEL_MILES tokens
  • A maximum of 5 tickets are available per user
  • A total of 5000 tickets are available in the prize draw
  • There will be 3 winners, each of the receiving 3 GLOBAL_STATUS tokens

Sample Prize Draw Request:

curl --request POST  
     --url <https://api.testcocrt.xyz/alpha/prize-draw>  
     --header 'Authorization: Bearer [YOUR_KEY_HERE]'  
     --header 'accept: application/json'  
     --header 'content-type: application/json'  
     --data '  
{  
  "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
  "prize_asset_type": "erc721",  
  "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
  "prize_asset_quantity": 3,
  "ticket_price": 100,  
  "max_tickets_per_user": 5,  
  "total_tickets": 5000,  
  "number_of_winners_to_draw": 3,
}
'

Expected Response:

{  
  "data": {  
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "active",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [],
  }
}

Using Start & End Dates, and Auto-Settling

📘

Use start & end dates to enable more control over when a prize draw can begin and for how long it will run.

  • All start dates & end dates must be in the future. Start dates cannot be later than or equal to end dates.
  • You may only pass an active status in the request body as a parameter if and only if a start date is not also passed in the body as a parameter (i.e. there is no defined start date).
  • If a start date is passed in the body as a parameter, the start date must be in the future and the status will default to draft whether an draft status is passed or not. When the start date arrives, the Co:Create platform will automatically set the status to active on your behalf.

📘

Disable Auto-Settling to get more granular control over when prizes are distributed

  • By default, the auto_settle parameter is set to true. In this configuration the prize draw will be automatically settled (winners will be picked and prizes distributed when the prize draw is over).
  • If you decide you need more control between completing the prize draw (/complete endpoint) and settling it (picking the winners and distributing prizes) you can set auto_settle to false. Then, upon prize draw completion it will stay in the completed stated until the /settle endpoint is called.

Purchasing a ticket

Continuing with the TRAVEL_MILES example outlined above, a user with the email address [email protected] would like to purchase 2 tickets for 200 TRAVEL_MILES. To do so, a POST request should be submitted to the ticket endpoint.

Example ticket purchase request for this scenario:

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/3b919f2f-caef-4523-93a4-740a53854bf7/ticket \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "amount": 2
}
'

Here's the response received:

{
  "data": [
  	{
    	"id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    	"org_id": "nifty_swanson_74",
    	"prize_draw_id": "3b919f2f-caef-4523-93a4-740a53854bf7", 
   	 	"email": "[email protected]",
    	"status": "purchased",
  	  "created_at": "2023-07-19T20:34:53.309155+00:00"
 	  },
  	{
    	"id": "23094834-dher-2423-123k-234iosfdu923",
    	"org_id": "nifty_swanson_74",
    	"prize_draw_id": "3b919f2f-caef-4523-93a4-740a53854bf7", 
    	"email": "[email protected]",
    	"status": "purchased",
    	"created_at": "2023-07-19T20:34:53.309155+00:00"
  	}
  ]
}

Completing a Prize Draw

In our example scenario, the prize draw has been well received by the community, and many tickets have been bought. The team would like to complete the prize draw and pick the winner. To complete the Prize Draw, a POST request is submitted to the /complete endpoint. (Note: Since the default auto_settle: true has not been changed while creating the prize draw, it will immediately go from complete to settling and (when the winners are picked and prizes distributed) to settled status.)

Example request for this scenario:

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/3b919f2f-caef-4523-93a4-740a53854bf7/complete \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \
'

Here's the response that is received immediately. Notice the status: "settling".

{  
  "data": {  
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "settling",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true,
    "winning_tickets": [],
  }
}

After a while, you can check the status of the prize draw again by querying its id...

curl --request GET \
     --url https://api.testcocrt.xyz/alpha/prize-draw/3b919f2f-caef-4523-93a4-740a53854bf7 \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \

...and receive the following response.

{  
  "data": {  
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "active",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true,
    "winning_tickets": [
    	"3b919f2f-caef-4523-93a4-740a53854bf7",
      "01c5e6cd-ca23-4233-970c-7f3b7b8b55f2",
      "0cda39f9-3596-4c81-9533-d3f101eaf37f"
    ],
  }
}

Notice that the winningTickets were updated as well with the ids of picked winners.

Getting details regarding a specific ticket

When we check the winningTickets picked while settling the prize draw in the previous section, we will notice that the [email protected] got lucky with his 3b919f2f-caef-4523-93a4-740a53854bf7 ticket. We can double-check that by getting information on that specific ticket.

curl --request GET \
     --url https://api.testcocrt.xyz/alpha/prize-draw/3b919f2f-caef-4523-93a4-740a53854bf7/ticket/3b919f2f-caef-4523-93a4-740a53854bf7  \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json' \

and expect to receive the ticket data with updated status:

{
  "data": {
    	"id": "3b919f2f-caef-4523-93a4-740a53854bf7",
    	"org_id": "nifty_swanson_74",
    	"prize_draw_id": "3b919f2f-caef-4523-93a4-740a53854bf7", 
   	 	"email": "[email protected]",
    	"status": "winner",
  	  "created_at": "2023-07-19T20:34:53.309155+00:00"
 	  }
}

Prize Draw State Management

A prize draw operates with a dynamic flow governed by various states. Initially, a prize draw can be established in either an active or draft state. You can transition Prize draw between the following states: draft, active, paused, cancelled , completed, settling and settled using different endpoints in Prize Draw API.

While you can find a detailed description of each state capacity below, we would also like to share a diagram showing how to navigate between available states:

Transitions between states in Prize Draw API

Transitions between states in Prize Draw API

Pause

Invoking /pause endpoint moves a prize draw from active to paused state. When a prize draw is paused, users cannot purchase tickets. From this state the prize draw can either be reactivated to its 'active' state or be completely canceled.

Pause Example Request

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/3b919f2f-caef-4523-93a4-740a53854bf7/pause \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Pause Example Response

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "paused",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [],
  }
}

Resume

Invoking /resume endpoint move a prize draw from to active state. The only state in which users can purchase tickets. You can /resume only from draft and paused states.

Resume Example Response

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/3b919f2f-caef-4523-93a4-740a53854bf7/resume \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Resume Example Request

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "active",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [],
  }
}

Cancel

Calling /cancel moves prize draw to canceled state end effectively terminates a prize draw. You can cancel from active and paused states.

Cancel Example Request

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/e2a47a9d-0b6c-4878-9537-c5fbfa298ecb/cancel \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Cancel Example Response

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "canceled",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [],
  }
}

Complete

Calling /complete moves a prize draw to complete state. Tickets cannot be purchased but winners are not yet picked. If auto_settle flag is set on a prize draw it will move automatically from complete to settling status.

Complete Example Request

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/e2a47a9d-0b6c-4878-9537-c5fbfa298ecb/complete \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Complete Example Response

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "complete",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [],
  }
}

Settle

Calling /settle moves a prize draw to setting and then - after the settling is concluded - to settled state. During the settling state prize draw winners are picked and prizes distributed. Time spent in settling state may vary depending on amount of winners. The best way to check whether the prize draw achieved settled status is to query the GET /prize-draw/:prize_draw_id API endpoint

Settle Example Request

curl --request POST \
     --url https://api.testcocrt.xyz/alpha/prize-draw/e2a47a9d-0b6c-4878-9537-c5fbfa298ecb/complete \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]' \
     --header 'accept: application/json'

Settle Example Response

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "settling",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [],
  }
}

After a time you can call:

Get Example Request

curl --request GET \
     --url https://api.testcocrt.xyz/alpha/prize-draw/e2a47a9d-0b6c-4878-9537-c5fbfa298ecb \
     --header 'Authorization: Bearer [YOUR_KEY_HERE]'

Get Example Response after the prize draw settled

{
  "data": {
    "id": "3b919f2f-caef-4523-93a4-740a53854bf7",  
    "org_id": "nifty_swanson_74",  
    "ticket_asset_id": "d56a253a-7b04-41f0-9cd2-04318877afd2",  
    "prize_asset_id": "002b0807-48e1-43f5-8432-d018c6d0eadb",  
    "prize_asset_type": "erc721",  
    "prize_asset_token_id": null,  
    "prize_asset_quantity": 3,
    "ticket_price": 100,  
    "max_tickets_per_user": 5,  
    "total_tickets": 5000,  
    "number_of_winners_to_draw": 3,
    "start_date": null,  
    "end_date": null,
    "status": "settled",  
    "created_at": "2023-07-19T20:34:53.309155+00:00",
    "auto_settle": true
    "winning_tickets": [
    	"3b919f2f-caef-4523-93a4-740a53854bf7",
      "01c5e6cd-ca23-4233-970c-7f3b7b8b55f2",
      "0cda39f9-3596-4c81-9533-d3f101eaf37f"
    ],
  }
}

👍

Get Help

If you get stuck at any time, reach out to us on Discord or contact us via email at [email protected].

Updated about 1 year ago