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

# Donation Configs

> Create and list donation configs for your project

<Badge icon="shield" color="purple" shape="pill">
  Requires <span style={{ color: '#7E22CE', fontWeight: '800' }}>partner</span> scope
</Badge>

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](/core-api/donation-configs). For aggregate stats and donor rankings on configs you own, see [Config Stats](/partner-api/config-stats) and [Config Leaderboard](/partner-api/config-leaderboard).

***

## Create a config

[`POST /configs`](/api-reference/create-a-config)

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

```bash theme={null}
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`

```json theme={null}
{
  "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"
    }
  ]
}
```

<Note>
  Weights in responses are strings to preserve full precision for values beyond
  `Number.MAX_SAFE_INTEGER`. Charity objects match the [Charities](/core-api/charities) shape, plus
  `weight`.
</Note>

**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`](/api-reference/list-configs)

Returns a paginated list of all configs created by your developer project.

```bash theme={null}
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**

```json theme={null}
{
  "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"
        }
      ]
    }
  ]
}
```

## Related endpoints

* [Get or delete a config by ID](/core-api/donation-configs) (Core scope)
* [Config stats](/partner-api/config-stats)
* [Config donor leaderboard](/partner-api/config-leaderboard)