# twitr.sh Twitter Giveaway Draw

> twitr.sh Twitter Giveaway Draw is a paid API for AI agents from twitr.sh, paid per call via x402, $1.2012/call, status unknown (last checked 2026-09-14).

Runs a provably fair, crypto-random winner selection from a tweet's replies with configurable eligibility filters like retweet, follow, hashtag, keyword, follower count, and account age requirements.

## Facts

- Endpoint: POST https://twitr.sh/api/tools/draws
- Price: $1.2012/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/twitr-sh-twitter-giveaway-draw-a02d0130
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap__Ud_cKZLw_sxnyDQXWLeX

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability twitr-sh-twitter-giveaway-draw-a02d0130 -d '<json body>'
```

Example prompt: Pick 3 winners and 2 backups from the giveaway tweet at https://x.com/myproject/status/1234567890, expecting about 2000 entries — only eligible if they retweeted, follow @myproject, and included #MyGiveaway in their reply.

## When to prefer this

Use this endpoint when you need a verifiably fair, auditable winner selection from a Twitter/X giveaway with complex eligibility rules. It is ideal when you need to enforce retweet, follow, hashtag, or account-quality conditions simultaneously and want a fixed, predictable price based on estimated reply volume rather than per-reply billing. Prefer it over manual selection or simple random tools when transparency and fairness matter for your audience.

## Known failure modes

- Tweet URL not found or invalid — returns error with URL validation message
- Estimated entries ceiling exceeded — price may not cover actual reply volume
- Insufficient eligible replies after filtering — may return fewer winners than requested
- Twitter/X API rate limit or access error — upstream failure propagated
- mustFollowUsername account doesn't exist or is private — filter cannot be validated
- Payment of 1.2012 USDC not completed — 402 response blocking execution

## How this service works

Run a provably fair giveaway on X/Twitter: pick crypto-random winners from a tweet's replies, with retweet, follow, hashtag, keyword, minimum-follower, and account-age conditions. Fixed price set upfront from your estimated entry count.

## Output

Returns a ranked list of selected winners and optional backup winners drawn crypto-randomly from eligible replies, after applying all specified eligibility filters (retweet status, follow status, required hashtags/keywords/mentions, minimum followers, account age, language, and uniqueness constraints).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "tweetUrl": {
   "type": "string",
   "description": "Full tweet URL (https://x.com/user/status/ID)."
  },
  "backupCount": {
   "type": "integer"
  },
  "mustRetweet": {
   "type": "boolean"
  },
  "winnerCount": {
   "type": "integer",
   "minimum": 1
  },
  "filterLanguage": {
   "type": "string"
  },
  "estimatedEntries": {
   "type": "integer",
   "maximum": 10000,
   "minimum": 1,
   "description": "Expected replies inspected — drives the fixed price (default 1000)."
  },
  "requiredHashtags": {
   "type": "array",
   "items": {
    "type": "string"
   }
  },
  "requiredKeywords": {
   "type": "array",
   "items": {
    "type": "string"
   }
  },
  "requiredMentions": {
   "type": "array",
   "items": {
    "type": "string"
   }
  },
  "uniqueAuthorsOnly": {
   "type": "boolean"
  },
  "filterMinFollowers": {
   "type": "integer"
  },
  "mustFollowUsername": {
   "type": "string"
  },
  "filterAccountAgeDays": {
   "type": "integer"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "items": [
   {
    "id": "a1b2c3d4e5f67890",
    "tweetId": "2079908425904042170",
    "winners": [
     {
      "tweetId": "1893710452812718080",
      "username": "builders_gonna"
     }
    ],
    "totalEntries": 512,
    "validEntries": 498
   }
  ],
  "runId": "tw_example",
  "payment": {
   "amount": "0.601200",
   "currency": "USD",
   "protocol": "x402"
  },
  "duration": 6
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/twitr-sh-twitter-giveaway-draw-a02d0130/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from twitr.sh](https://www.zero.xyz/host/twitr.sh/llms.txt)