---
title: "Create a new giveaway"
method: POST
path: "/v1/giveaway"
tags: ["giveaway"]
---

# Create a new giveaway

`POST /v1/giveaway`

Create a giveaway that automatically enters tippers during the specified window.

**Authentication required**: Account JWT (Bearer token) must be provided.

Tips to ANY of the creator's earning wallets (smart_account rows) during the giveaway window will create entries. The giveaway is tied to the authenticated account, not a specific wallet address.

Management operations (update, draw, cancel) require the same account JWT used to create the giveaway. Only the creator can manage their giveaway.

Currently limited to USDC tips on Base and Base Sepolia networks.

## Headers

- `authorization` string, nullable — Bearer <account_jwt>

## Request body

- CreateGiveawayRequest — Request body for creating a giveaway.
  - `title` string, required — Short title for the giveaway
  - `description` string, required — Description of the giveaway and prizes
  - `minimum_tip_usd` union, required — Minimum tip in USD to qualify for 1 entry
    - number
    - string
  - `start_at` string, date-time, required — When the giveaway starts accepting entries (must be in the future)
  - `end_at` string, date-time, required — When the giveaway stops accepting entries
  - `allow_multiple_entries` boolean — If true, floor(tip_amount / min_tip) = number of entries. If false, 1 entry per qualifying tip.
  - `num_winners` integer — Number of winners to draw
  - `selection_mode` 'random' | 'manual' — How winners are selected for a giveaway.
  - `network` string — Network for the giveaway (must match tip network for entries to be created)

## Response `200`

Successful Response

- CreateGiveawayResponse — Response for giveaway creation.
  - `giveaway` GiveawayResponse, required — Response for giveaway details.
    - `id` string, required
    - `creator_account_id` string, required
    - `earning_address` string, nullable
    - `creator_handle` string, nullable
    - `creator_ens_name` string, nullable
    - `creator_base_name` string, nullable
    - `title` string, required
    - `description` string, required
    - `minimum_tip_usd` string, required
    - `allow_multiple_entries` boolean, required
    - `num_winners` integer, required
    - `selection_mode` string, required
    - `network` string, required
    - `token_symbol` string, required
    - `start_at` string, date-time, required
    - `end_at` string, date-time, required
    - `status` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `drawn_at` string, date-time, nullable
    - `is_winner` boolean, nullable
    - `stats` GiveawayStatsResponse — Statistics for a giveaway.
      - `total_entries` integer, required — Total number of entries across all participants
      - `unique_participants` integer, required — Number of unique tippers who entered
      - `total_tips_usd` string, required — Total USD value of tips that created entries
    - `creator_address` string, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/versions/f286b48a8105/schema)