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. Configs and their recipient mappings are permanent: they cannot be deleted or archived, even if no donations have been recorded. Published config IDs can receive funds later. 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. The standard API fee is 20% (2,000 basis points), set by the server. Each config stores its fee when created; changes to the standard rate do not change that stored fee. Re-posting an identical set of beneficiaries for the same project at the same fee is idempotent: the API returns the existing config with status 201. The fee is part of the config ID, so posting those beneficiaries after a fee change creates a different config.

curl -X POST https://api.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://api.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://api.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

Config deletion is disabled

DELETE /configs/{configId} remains available to return an explicit error to existing clients. It requires an API key and never deletes or archives a config. Requests for an existing config return 403 Forbidden, including when the caller owns the config and it has no recorded donations.

{
  "error": "Config deletion is disabled; recipient mappings are permanent.",
  "code": "FORBIDDEN"
}

Error responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid config ID format
`403`	`FORBIDDEN`	Config deletion is disabled
`404`	`NOT_FOUND`	Config not found

Getting Started

Developer

API

Blockchain

AI & LLMs

For Non-profits

Other

Create a config

List configs

Get a config by ID

Config deletion is disabled

​Create a config

​List configs

​Get a config by ID

​Config deletion is disabled

​Related endpoints

Create a config

List configs

Get a config by ID

Config deletion is disabled

Related endpoints