Donation Configs

Requires partner scope 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. To inspect or delete a config by ID, see Core API: Donation Configs. 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 verified 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 or delete a config by ID (Core scope)
Config stats
Config donor leaderboard

Getting Started

Developer

Core API

Partner API

Blockchain

AI & LLMs

For Non-profits

Other

Create a config

List configs

​Create a config

​List configs

​Related endpoints

Create a config

List configs

Related endpoints