vegabot-py-sdk 0.2.0

Official Python SDK for the Vega API (Discord giveaways).

vegabot-py-sdk (Python)

Official Python SDK for the Vega API — Discord giveaways, required-server management, and the membership gate. Included with a Vega whitelabel license.

pip install vegabot-py-sdk

Python 3.9+.

Quick start

import os
from vega import VegaClient

vega = VegaClient(api_key=os.environ["VEGA_API_KEY"])

me = vega.me()                 # {"guildId": ..., "license": {...}}
active = vega.list_giveaways()

Get your key from the dashboard: Whitelabel → API → Generate key (license owner only). A key is scoped to one Discord server. Keep it server-side. Use the client as a context manager to auto-close:

with VegaClient(api_key=...) as vega:
    vega.list_giveaways()

Giveaways

res = vega.create_giveaway(
    prize="Nitro",
    channel_id="123456789012345678",
    duration_seconds=86_400,
    winners=1,
    description="Good luck!",
    requirements=[{"requiredGuildId": "987654321098765432"}],
)

active = vega.list_giveaways()
one = vega.get_giveaway(res["giveawayId"])     # {"giveaway":..., "entryCount":..., "winnerIds":[...]}
vega.end_giveaway(res["giveawayId"])
vega.reroll_giveaway(res["giveawayId"], winners=2)

Required servers

vega.register_server(required_guild_id="987...", name="Main Server", invite_url="https://discord.gg/abc")
servers = vega.list_servers()
vega.delete_server("987...")

Membership gate

result = vega.check_membership(user_id="111...", required_guild_id="987...")
print(result["inServer"], result["hasRole"])

Settings

settings = vega.get_settings()

Reacting to giveaway events

Two options: poll (no public URL) or receive webhooks.

Option A — polling (no public URL needed)

listen polls the event feed and calls your handler for each event, in order. It blocks, so run it in a thread.

import threading

def handle(event):
    if event["event"] == "giveaway.ended":
        print("winners", event["data"]["winnerIds"])

stop = threading.Event()
threading.Thread(target=vega.listen, args=(handle,), kwargs={"stop": stop}, daemon=True).start()
# ... later: stop.set()

By default only events after listen starts are delivered; pass after=0 to replay everything still in the feed. You can also poll manually with vega.list_events(after, limit) and track the last id.

Option B — webhooks

Set a delivery URL (dashboard API → Webhooks, or vega.set_webhook(url)). Vega POSTs signed events to it. Verify the X-Vega-Signature header. construct_event verifies and parses in one call:

from vega import construct_event, VegaSignatureError

# Flask, needs the RAW body
@app.post("/vega/webhook")
def webhook():
    try:
        event = construct_event(request.get_data(), request.headers.get("X-Vega-Signature"), SECRET)
    except VegaSignatureError:
        return "", 401
    if event["event"] == "giveaway.ended":
        print(event["data"]["winnerIds"])
    return "", 200

Prefer verifying yourself? Use verify_webhook(raw_body: bytes, header, secret) -> bool.

More examples (Flask, FastAPI, polling) are in the docs.

Errors

Failed calls raise VegaApiError with .status, .code, and .detail.

from vega import VegaApiError
try:
    vega.get_giveaway(999999)
except VegaApiError as e:
    if e.status == 404:
        print("not found")

License

MIT