PawSharp is a Discord API wrapper for C#. It's split into independent packages — grab the full client for a bot, or pick just the pieces you need.
Current release: 1.1.0-alpha.3. See the versioning policy and MIGRATION.md if upgrading from an earlier alpha.
dotnet add package PawSharp.Client --version 1.1.0-alpha.3using PawSharp.Client;
using PawSharp.Core.Enums;
string token = Environment.GetEnvironmentVariable("DISCORD_TOKEN")
?? throw new InvalidOperationException("Set DISCORD_TOKEN before running.");
var client = new PawSharpClientBuilder()
.WithToken(token)
.WithIntents(GatewayIntents.AllNonPrivileged | GatewayIntents.MessageContent)
.UseConsoleLogging()
.Build();
client.OnMessageCreated(async evt =>
{
if (evt.Author?.IsBot == true) return;
if (evt.Content == "!ping")
await client.SendMessageAsync(evt.ChannelId, "Pong!");
});
await client.ConnectAsync();
await Task.Delay(Timeout.Infinite);That's it. The builder wires up the REST client, gateway, cache, and logging with sensible defaults.
export DISCORD_TOKEN="your-bot-token-here"
dotnet runPawSharp is modular by design. Install only what you need.
| Package | Purpose | Depends on |
|---|---|---|
PawSharp.Client |
Top-level DiscordClient — fluent builder, DI, connection state, 130+ convenience methods |
Core, API, Gateway, Cache |
PawSharp.Core |
Shared entities, enums, builders, validation, serialization | — |
PawSharp.API |
Raw REST client, 140+ endpoints, auto rate limiting, telemetry | Core |
PawSharp.Gateway |
WebSocket, heartbeat, resume, reconnection, sharding, 40+ typed events | Core, API, Cache |
PawSharp.Commands |
Prefix commands via [Command], preconditions, type conversion, middleware |
Core, API, Client |
PawSharp.Interactions |
Slash commands, components, modals, autocomplete, context menus | Core, API, Gateway |
PawSharp.Interactivity |
Pagination, wait-for-input, polls, confirmation dialogs | Core, Client |
PawSharp.Voice |
Voice gateway, UDP audio, Opus encode/decode, DAVE E2EE | Core, API, Gateway, Client |
PawSharp.Cache |
In-memory and Redis caching, per-entity TTL, LRU eviction, health checks | Core |
REST API — 140+ endpoints covering messages, channels, guilds, members, roles, webhooks, threads, reactions, slash commands, audit logs, auto-moderation, scheduled events, stage instances, stickers, soundboard, polls, entitlements, and onboarding. All with typed models and automatic rate limiting.
Gateway — WebSocket lifecycle with automatic resume, heartbeat monitoring, and exponential-backoff reconnection. Over 40 typed events with intent filtering. Built-in sharding with auto-rebalancing for large bots.
Commands — Attribute-based prefix commands with middleware, type conversion (14 built-in plus custom), and preconditions for permissions, ownership, roles, cooldowns, and scoping. Auto-discover modules with assembly scanning.
Interactions — Slash command registration, buttons, select menus, modals, autocomplete, and context menus. The InteractionHandler routes interactions with error recovery so users get feedback instead of silent timeouts.
Interactivity — Paginated messages (reactions or buttons), confirmations, input prompts, polls. Configurable timeouts.
Voice — Discord Voice Protocol v8 with UDP audio, Opus codec (pure .NET via Concentus, no native DLLs), and DAVE E2EE (MLS / RFC 9420) with X25519 + Ed25519 + AES-128-GCM. Multiple simultaneous connections.
Caching — Pluggable in-memory or Redis cache with per-entity TTL, LRU eviction, health checks, and telemetry. Dynamic provider swapping with circuit breaker fallback.
- DEVELOPERS_GUIDE.md — Setup, first bot, configuration, best practices
- REST_API_GUIDE.md — Full REST endpoint reference with examples
- GATEWAY_GUIDE.md — Events, lifecycle, sharding, middleware
- CACHING_GUIDE.md — In-memory and Redis caching strategies
- PATTERNS_GUIDE.md — Moderation, logging, pagination patterns
- VOICE_GUIDE.md — Voice connections, Opus, DAVE E2EE
- ERROR_HANDLING.md — Exception hierarchy, recovery strategies
- MIGRATION.md — Breaking changes between alpha versions
- TROUBLESHOOTING.md — Common issues and fixes
The examples/ directory has three working bots:
- ModerationBot — Gateway events, REST operations, moderation logic. Uses the low-level API.
- MusicBot — DI setup, commands, voice integration. Shows the module pattern.
- DashboardBot — ASP.NET integration, interaction handlers, webhook verification. HTTP interaction mode.
Each example has its own README with setup instructions.
PawSharp follows Semantic Versioning. Until 1.0.0, minor bumps may include breaking changes. See VERSIONING_POLICY.md for details.
Pull requests welcome. Read CONTRIBUTING.md first — it covers code style, testing, docs, and the release process.
MIT. See LICENSE.