Donation Configs

Requires API key A config defines 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. 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 }. hex is the on-chain bytes32. base58 is the same value encoded for Solana. Either form works in path parameters. For aggregate stats and donor rankings on configs you own, see Config Stats and Config Leaderboard.

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. Re-posting an identical set of beneficiaries for the same project is idempotent: the API returns the existing config with status 201.

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 }
    ]
  }'

Request body

Field	Type	Description
`charityBeneficiaries`	array	1-5 charity beneficiaries with weights
`charityBeneficiaries[].charityId`	string	ID of a participating charity
`charityBeneficiaries[].weight`	integer	Relative weight, must be greater than `0`

Response 201

{
  "id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
  "users": [],
  "charities": [
    {
      "id": "charity_abc",
      "slug": "red-cross",
      "name": "American Red Cross",
      "logo": "https://...",
      "website": "https://redcross.org",
      "mission": "To prevent and alleviate human suffering...",
      "address": "431 18th St NW",
      "city": "Washington",
      "state": "DC",
      "country": "US",
      "zipCode": "20006",
      "taxId": "53-0196605",
      "socials": {
        "blog": null,
        "twitter": "RedCross",
        "facebook": null,
        "instagram": null,
        "linkedin": null,
        "youtube": null,
        "blogUrl": null,
        "twitterUrl": "https://x.com/RedCross",
        "twitterHandle": "RedCross",
        "facebookUrl": null,
        "facebookHandle": null,
        "instagramUrl": null,
        "instagramHandle": null,
        "linkedinUrl": null,
        "linkedinHandle": null,
        "youtubeUrl": null,
        "youtubeHandle": null,
        "youtubeChannelId": null
      },
      "isEnabled": true,
      "weight": "60"
    }
  ]
}

Weights in responses are strings to preserve full precision for values beyond Number.MAX_SAFE_INTEGER. Charity objects match the Charities shape, plus weight.

Error responses

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 project.

curl https://www.donate.gg/api/v1/configs \
  -H "donate-api-key: YOUR_API_KEY"

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Results per page, max `200`
`cursor`	string	-	Cursor from previous `pageKey` for next page

Response

{
  "pageKey": "next_cursor_string",
  "response": [
    {
      "id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
      "users": [],
      "charities": [
        {
          "id": "charity_abc",
          "slug": "red-cross",
          "name": "American Red Cross",
          "weight": "60",
          "...": "other charity fields"
        }
      ]
    }
  ]
}

Get a config by ID

GET /configs/{configId} Returns a single config with its user and charity beneficiaries. Any valid API key can fetch a config by ID. Aggregate donation stats are not included here — use GET /configs/{configId}/stats for that.

curl https://www.donate.gg/api/v1/configs/0x1234...abcd \
  -H "donate-api-key: YOUR_API_KEY"

Path parameters

Parameter	Description
`configId`	The config ID (hex string or base58 encoding)

Response

{
  "id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
  "users": [],
  "charities": [
    {
      "id": "charity_abc",
      "slug": "red-cross",
      "name": "American Red Cross",
      "logo": "https://...",
      "website": "https://redcross.org",
      "mission": "To prevent and alleviate human suffering...",
      "address": "431 18th St NW",
      "city": "Washington",
      "state": "DC",
      "country": "US",
      "zipCode": "20006",
      "taxId": "53-0196605",
      "socials": {
        "blog": null,
        "twitter": "RedCross",
        "facebook": null,
        "instagram": null,
        "linkedin": null,
        "youtube": null,
        "blogUrl": null,
        "twitterUrl": "https://x.com/RedCross",
        "twitterHandle": "RedCross",
        "facebookUrl": null,
        "facebookHandle": null,
        "instagramUrl": null,
        "instagramHandle": null,
        "linkedinUrl": null,
        "linkedinHandle": null,
        "youtubeUrl": null,
        "youtubeHandle": null,
        "youtubeChannelId": null
      },
      "isEnabled": true,
      "weight": "60"
    }
  ]
}

Error responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid config ID format
`404`	`NOT_FOUND`	No config found with the given ID

Delete a config

DELETE /configs/{configId} Deletes a config you own. 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"

Path parameters

Parameter	Description
`configId`	The config ID (hex string or base58 encoding)

Configs that have existing donations or linked entities (like partner contracts) cannot be deleted. Only the project that created the config can delete it.

Error responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid config ID format
`403`	`FORBIDDEN`	You do not own this config
`404`	`NOT_FOUND`	Config not found
`409`	`HAS_DONATIONS`	Config has existing donations and cannot be deleted
`409`	`HAS_LINKED_ENTITIES`	Config has linked entities and cannot be deleted

Getting Started

Developer

API

Blockchain

AI & LLMs

For Non-profits

Other

Create a config

List configs

Get a config by ID

Delete a config

​Create a config

​List configs

​Get a config by ID

​Delete a config

​Related endpoints

Create a config

List configs

Get a config by ID

Delete a config

Related endpoints