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

# Beneficiaries and API v2

> Search charities and campaigns, inspect a beneficiary, and create a weighted donation config

Use `https://api.donate.gg/api/v2` for configs containing charities, campaigns, or both.
Supported beneficiary types are `charity` and `campaign`. Campaign sources are `donate` for
campaigns created on Donate and `tiltify` for imported Tiltify campaigns. Direct user recipients
and research beneficiaries are not enabled in v2.

Public GET requests may omit an API key. Creating a config and listing your project's configs
require the same `donate-api-key` header used by v1. Keep that key on your server.
External integrations should call from their server: anonymous reads do not imply browser CORS
access from arbitrary sites. The API's browser CORS allowlist is for Donate's own origins.

## Search for a beneficiary

```bash theme={null}
curl 'https://api.donate.gg/api/v2/beneficiaries/search?term=relief&limit=10'
```

```json theme={null}
{
  "response": [
    {
      "type": "charity",
      "id": "charity_abc",
      "name": "Example Relief",
      "logo": "https://www.donate.gg/web-app-manifest-512x512.png"
    },
    {
      "type": "campaign",
      "id": "campaign_abc",
      "name": "Relief Fundraiser",
      "logo": "https://images.example.org/campaign-cover.png",
      "source": "tiltify"
    }
  ]
}
```

`term` is required, with 1–200 characters after trimming. `limit` defaults to 10 and accepts
1–50. This is a bounded autocomplete: there is no cursor, total count, or empty-query browse.
Search returns only beneficiaries currently selectable for a new config.
Every v2 beneficiary `logo` is an absolute HTTP(S) image URL. Search, profiles, configs and coins
use the campaign's source image or first uploaded image. Missing or unavailable branding uses
the Donate placeholder, including hidden historical beneficiaries; render it like any other image.

The unified endpoint defaults to **All** when `type` is omitted. Select one or more types with
pipe-separated flags. Ordering and duplicate flags do not change the selection:

```bash theme={null}
curl 'https://api.donate.gg/api/v2/beneficiaries/search?term=relief&type=charity'
curl 'https://api.donate.gg/api/v2/beneficiaries/search?term=relief&type=campaign'
curl 'https://api.donate.gg/api/v2/beneficiaries/search?term=relief&type=charity%7Ccampaign&campaignSource=tiltify'
```

`%7C` is the URL-encoded pipe (`|`). The last query includes matching charities and Tiltify
campaigns. `campaignSource` accepts either `donate` or `tiltify` as a single value; it filters
only the campaign portion of the selected types. With no `type`, charities are still included;
with `type=charity`, a valid source value has no effect. Unknown source values are always rejected.

Only `charity` and `campaign` type flags are enabled. An explicit empty selection, unknown flags,
`type=all`, `user` and `research` are rejected with HTTP 400. Omit `type` for All; research can be
added as a selectable type when it becomes available. Selected types are ranked together before
applying the shared result limit, without a separate quota for each type.

The existing single-type paths remain supported. Their `type` path segment accepts one type,
and only their campaign route accepts `campaignSource`:

```bash theme={null}
curl 'https://api.donate.gg/api/v2/beneficiaries/search/charity?term=relief'
curl 'https://api.donate.gg/api/v2/beneficiaries/search/campaign?term=relief&campaignSource=tiltify'
```

Search covers campaigns already added to Donate. It does not search Tiltify's entire website or
import a pasted URL. Campaign import is a separate Donate flow.

## Inspect the selected beneficiary

```bash theme={null}
curl 'https://api.donate.gg/api/v2/beneficiary/campaign/campaign_abc'
```

```json theme={null}
{
  "type": "campaign",
  "id": "campaign_abc",
  "name": "Relief Fundraiser",
  "logo": "https://images.example.org/campaign-cover.png",
  "source": "tiltify",
  "description": "Support our relief fundraiser.",
  "url": "https://www.donate.gg/campaigns/relief-fundraiser",
  "sourceUrl": "https://tiltify.com/@example/relief-fundraiser",
  "eligible": true
}
```

A charity profile has the same presentation fields and `eligible`, without `source` or
`sourceUrl`. `description` is plain text, not HTML; `url` links to the beneficiary on Donate.
A visible completed campaign remains readable with `eligible: false`; a hidden or
missing campaign returns 404. Eligibility can change after this read, so config creation checks
it again. The profile does not return a donation config: create one with the selected `type`
and `id` to retain your project's attribution.

## Create and inspect a config

```bash theme={null}
curl -X POST 'https://api.donate.gg/api/v2/configs' \
  -H 'donate-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"beneficiaries":[
    {"type":"charity","id":"charity_abc","weight":1},
    {"type":"campaign","id":"campaign_abc","weight":2}
  ]}'
```

The response is HTTP 201 with this shape; IDs below are illustrative:

```json theme={null}
{
  "id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
  "feeBps": "2000",
  "beneficiaries": [
    {
      "type": "charity",
      "id": "charity_abc",
      "name": "Example Relief",
      "logo": "https://www.donate.gg/web-app-manifest-512x512.png",
      "weight": "1"
    },
    {
      "type": "campaign",
      "id": "campaign_abc",
      "name": "Relief Fundraiser",
      "logo": "https://images.example.org/campaign-cover.png",
      "source": "tiltify",
      "weight": "2"
    }
  ]
}
```

* Supply 1–5 distinct `(type, id)` pairs. Weights must be positive, safe JSON integers. A weight
  of 2 receives twice the beneficiary allocation of a weight of 1. Response weights are strings.
  They are relative shares, not percentages: display `weight / sum(weights) × 100`. Weights
  `1` and `2` mean roughly 33.33% and 66.67% of the beneficiary allocation, not 1% and 2%.
  Fees are accounted for separately. Do not rewrite a saved config just to format percentages.
* A native campaign forwards its share to its retained receivers. The total number of final
  receiver allocations must also fit the five-recipient limit, so some combinations of campaigns
  are rejected even when the request contains fewer than five beneficiaries.
* Configs are permanent. An equivalent request for the same project and stored fee returns the
  existing config, including when a beneficiary later becomes unavailable. New selections must
  pass current eligibility and provider checks.
* `feeBps` is the stored config fee, not a current rate guarantee. Use the existing
  [effective-fee endpoint](https://docs.donate.gg/api/donation-configs.md#current-donation-fee) for current pricing.

`GET /api/v2/configs/{configId}` inspects a config publicly. `GET /api/v2/configs` lists your
project's supported configs with `limit` and `cursor`; the response is
`{ "response": [...], "pageKey": null }` on the last page, or a cursor string for another page. Config IDs accept hex or
base58. Hidden historical beneficiaries keep their identity but use an unavailable label.

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | Invalid fields, duplicate beneficiaries, or too many expanded recipients. |
| 400 | `BENEFICIARY_NOT_FOUND` | A selected ID does not exist. |
| 400 | `BENEFICIARY_NOT_ELIGIBLE` | A selected beneficiary cannot enter a new config. |
| 409 | `BENEFICIARY_UNAVAILABLE` | Routing or provider verification is temporarily unavailable. |
| 409 | `CONFIG_NOT_SUPPORTED` | The config contains direct user beneficiaries; inspect it through v1. |

## Browse campaigns and donating coins

```bash theme={null}
curl 'https://api.donate.gg/api/v2/campaigns?source=tiltify&limit=25'
curl 'https://api.donate.gg/api/v2/coins?beneficiaryType=campaign&campaignSource=tiltify&limit=25'
```

Campaign browsing accepts `source=donate|tiltify`; omitting it includes both. Displayed campaign
amounts cover donations through Donate, not the total shown on Tiltify.

Coins accept `beneficiaryType=charity|campaign`. `campaignSource` requires
`beneficiaryType=campaign` and refers to the campaign provider, not an on-chain donation source.
Filtered coin amounts and ranking use the actual allocated receipt amounts for the selected
beneficiaries. A native campaign's forwarded share is counted under that campaign, not again as
a direct charity share. Use `GET /api/v2/{chainId}/tokens/{address}` for current token routing.

## Keep v1 integrations working

V1 keeps its existing charity/user response shapes. Its campaign list includes native Donate
campaigns; v2 includes imported campaigns too. V1 config and token lookups that cannot represent
campaign beneficiaries return HTTP 409 `API_VERSION_UNSUPPORTED`, and v1 project config lists
exclude those configs before pagination. V2 excludes direct-user configs from its project list
and returns `CONFIG_NOT_SUPPORTED` for an exact lookup. Neither version silently drops a
recipient from a returned config.

Continue using the existing chain and donation endpoints with the returned config ID. V2 changes
beneficiary discovery and config representation; it does not create an automatic Tiltify payout.

## Upgrade an existing coin integration

Use the existing flow: add a Tiltify link on Donate, then find its campaign name in your
integration's beneficiary picker. Search is local discovery, not provider-wide search.

| Step | API to use |
| - | - |
| Find charities or campaigns | v2 beneficiary search; retain both `type` and `id` |
| Create a selection | v2 `POST /configs` with the existing server-held project key; save and reuse the returned ID |
| Display config recipients | v2 `GET /configs/{id}`; render `beneficiaries` by `type`, using `name`, `logo` and relative `weight` |
| Display a token's current and previous recipients | v2 `GET /{chainId}/tokens/{address}` |
| Link to a beneficiary or show its description | v2 `GET /beneficiary/{type}/{id}` |
| Show existing charity website/social fields | Keep v1 `GET /charities/{id}` for charity recipients |
| Read fees, config stats/leaderboards or token stats | Keep the existing v1 endpoints |
| Submit the on-chain donation | Keep using `id.base58` on Solana or `id.hex` where bytes32 is required |

Moving config creation alone is insufficient: v1 config and token detail reads reject graphs
containing campaigns. Move those display reads together. No recipient wallet address is needed
to create a coin's routing; the config ID retains that routing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.