Documentation Index
Fetch the complete documentation index at: https://docs.donate.gg/llms.txt
Use this file to discover all available pages before exploring further.
A config is the central concept in the Donate.gg Developer API. It defines a set of charity beneficiaries and how donations are split between them. When a donation is made on-chain, the config ID determines where funds go.
Each charity in a config has a weight that determines its share. Weights are relative: a charity with weight 2 receives twice as much as one with weight 1.
Config IDs are returned as { "hex": string, "base58": string }. The hex form is the on-chain bytes32; the base58 form is a Solana-friendly encoding of the same value.
Create a config
POST /configs
Creates a new config with charity beneficiaries. At least one beneficiary is required, and at most 5 beneficiaries are allowed.
curl -X POST https://www.donate.gg/api/v1/configs \
-H "donate-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"charityBeneficiaries": [
{ "charityId": "charity_abc", "weight": 60 },
{ "charityId": "charity_def", "weight": 40 }
]
}'
| Field | Type | Description |
|---|
charityBeneficiaries | array | 1–5 charity beneficiaries with weights |
charityBeneficiaries[].charityId | string | ID of a verified charity |
charityBeneficiaries[].weight | integer | Relative weight, must be greater than 0 |
201
{
"id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
"charities": [
{
"id": "charity_abc",
"slug": "red-cross",
"name": "American Red Cross",
"logo": "https://...",
"website": "https://redcross.org",
"address": "431 18th St NW",
"blog": "https://example.com",
"twitter": "redcross",
"facebook": "redcross",
"instagram": "redcross",
"linkedin": "redcross",
"youtube": "redcross",
"city": "Washington",
"state": "DC",
"country": "US",
"zipCode": "20006",
"taxId": "53-0196605",
"isEnabled": true,
"isVerified": true,
"weight": "60"
}
],
"users": []
}
Weights in responses are strings to preserve full precision for values beyond
Number.MAX_SAFE_INTEGER.
| Status | Code | Description |
|---|
400 | VALIDATION_ERROR | Missing or invalid fields |
400 | CHARITY_NOT_FOUND | One or more charity IDs don’t exist |
400 | DUPLICATE_CHARITY_IDS | The same charity appears more than once |
400 | INVALID_JSON | Request body is not valid JSON |
List configs
GET /configs
Returns a paginated list of all configs created by your developer account.
curl https://www.donate.gg/api/v1/configs \
-H "donate-api-key: YOUR_API_KEY"
| Parameter | Type | Default | Description |
|---|
limit | integer | 50 | Results per page, max 200 |
cursor | string | - | Cursor from previous pageKey for next page |
{
"pageKey": "next_cursor_string",
"response": [
{
"id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
"charities": [
{
"id": "charity_abc",
"slug": "red-cross",
"name": "American Red Cross",
"weight": "60",
"...": "other charity fields"
}
],
"users": []
}
]
}
Get a config by ID
GET /configs/{configId}
Returns a single config with its beneficiaries and aggregate donation stats.
curl https://www.donate.gg/api/v1/configs/0x1234...abcd \
-H "donate-api-key: YOUR_API_KEY"
| Parameter | Description |
|---|
configId | The config ID (hex string) |
{
"id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
"charities": [
{
"id": "charity_abc",
"slug": "red-cross",
"name": "American Red Cross",
"weight": "60",
"...": "other charity fields"
}
],
"users": [],
"stats": {
"channels": {
"1": { "0xA0b8...": "1000000000000000000" },
"900": { "So11...": "500000000" }
},
"usdDonatedE6": "150000000",
"donationCount": "42",
"firstDonationDate": "2025-01-15T12:00:00.000Z",
"lastDonationDate": "2026-04-20T18:30:00.000Z"
}
}
stats object includes:
| Field | Type | Description |
|---|
channels | object | { [chainId]: { [tokenAddress]: totalGrossAtomicVolume } } |
usdDonatedE6 | string | Total USD donated × 10^6 |
donationCount | string | Total number of donations |
firstDonationDate | string | null | ISO 8601 timestamp of first donation, or null |
lastDonationDate | string | null | ISO 8601 timestamp of most recent donation, or null |
| Status | Code | Description |
|---|
404 | NOT_FOUND | No config found with the given ID |
Delete a config
DELETE /configs/{configId}
Deletes a config. Returns 204 No Content on success with an empty body.
curl -X DELETE https://www.donate.gg/api/v1/configs/0x1234...abcd \
-H "donate-api-key: YOUR_API_KEY"
| Parameter | Description |
|---|
configId | The config ID (hex string) |
Configs that have existing donations or linked entities (e.g. partner contracts) cannot be
deleted.
| Status | Code | Description |
|---|
404 | NOT_FOUND | Config not found |
403 | FORBIDDEN | You do not own this config |
409 | HAS_DONATIONS | Config has existing donations and cannot be deleted |
409 | HAS_LINKED_ENTITIES | Config has linked entities and cannot be deleted |
