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
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:
%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:
Inspect the selected beneficiary
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
- 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: displayweight / sum(weights) × 100. Weights1and2mean 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.
feeBpsis the stored config fee, not a current rate guarantee. Use the existing effective-fee endpoint 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.
Browse campaigns and donating coins
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 409API_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.
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.