Add a "Donate tokens" button

A Donate tokens button in a README takes visitors to the project's donation page on moochy.dev. This page is an exact recipe: a person or an AI coding agent working inside a repository can follow it step by step without guessing. Raw Markdown of this page: https://moochy.dev/docs/donate-button.md.

The button is a plain image link. Adding it needs no account, no key, and no token.

Recipe#

1. Find the project's provider and path#

Run, in the repository:

url=$(git remote get-url origin)
host=$(printf '%s\n' "$url" | sed -E 's#^[a-z+]+://##; s#^[^@/]*@##; s#[:/].*$##')
path=$(printf '%s\n' "$url" | sed -E 's#^[a-z+]+://##; s#^[^@/]*@##; s#^[^:/]+(:[0-9]+)?[:/]##; s#/+$##; s#\.git$##')
case "$host" in github.com) provider=github ;; gitlab.com) provider=gitlab ;; *) provider= ;; esac
echo "$provider $path"

Stop and tell the maintainer instead of guessing when:

• provider is empty: only public repositories on github.com and gitlab.com can receive donations;
• provider is github and path does not have exactly one / (GitHub paths are always owner/name);
• there is no origin remote: ask which remote is the public one, and use git remote get-url <name>.

GitLab paths keep every group and subgroup (group/subgroup/project, up to 20 levels). Each segment is 1 to 100 characters from A–Z a–z 0–9 . _ - and starts with a letter or digit. Keep the case as it appears in the URL. Never print or store the remote URL itself: it can contain a token (https://user:token@github.com/…).

2. Check that the project is on Moochy, and get its addresses#

curl -fsS "https://moochy.dev/api/v1/projects/$provider/$path"

The answer is public and contains no donor or amount. For github and tinyhttp/arrow:

{"claimed": true, "donate_url": "https://moochy.dev/p/github/tinyhttp/arrow/donate", "button_url": "https://moochy.dev/p/github/tinyhttp/arrow/button.svg", "docs": "/docs/donate-button.md"}

• "claimed": true: go to step 3, and use button_url and donate_url exactly as returned.
• "claimed": false: do not add the button yet (it would show "project not found"). Tell the maintainer what is in Not on Moochy yet.
• 404 with an error message: the provider or path is not valid; recheck step 1.

With the Moochy app installed, moochy button does steps 1 to 3 at once: it reads the git remote (offline) and prints the snippet. Options: --repo <path>, --provider github|gitlab, --style mascot|text|compact, --theme light|dark|auto, --size s|m|l, --label TEXT, --format markdown|html|rst.

Project addresses. A project's pages live at https://moochy.dev/p/<provider>/<path>: /p/github/tinyhttp/arrow, /p/gitlab/group/subgroup/project. Add /button.svg for the image and /donate for the donation page; on GitLab these come after GitLab's /-/ separator (/p/gitlab/group/subgroup/project/-/button.svg, /-/donate), so nested group names stay unambiguous. For GitHub, the short form without the provider (/p/tinyhttp/arrow/button.svg) also works and always will, so existing buttons keep working; moochy button prints it for GitHub projects.

3. Pick the snippet#

Replace BUTTON_URL and DONATE_URL with the values from step 2. The default button (mascot and text, light, medium) needs no options.

Markdown (README.md; works on GitHub, GitLab, and most package registries):

[![Donate tokens](BUTTON_URL)](DONATE_URL)

HTML, following the reader's light or dark theme (GitHub and GitLab README files; recommended on GitHub):

<a href="DONATE_URL">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="BUTTON_URL?theme=dark">
    <img alt="Donate tokens" height="36" src="BUTTON_URL">
  </picture>
</a>

HTML, one theme (when the README already uses HTML badges):

<a href="DONATE_URL"><img alt="Donate tokens" height="36" src="BUTTON_URL"></a>

reStructuredText (README.rst):

.. image:: BUTTON_URL
   :target: DONATE_URL
   :alt: Donate tokens

For example, a GitLab project in a subgroup:

[![Donate tokens](https://moochy.dev/p/gitlab/group/subgroup/project/-/button.svg)](https://moochy.dev/p/gitlab/group/subgroup/project/-/donate)

Keep the alt text "Donate tokens" (or the label you chose): screen readers announce it, and it shows when the image cannot load. Set height to match the size: 28 for s, 36 for m, 44 for l.

4. Put it in the README#

1. Use the README at the repository root: README.md, README.rst, or README (in that order). If there is none, ask the maintainer before creating one.
2. Avoid duplicates. Search the README for moochy.dev/p/ and moochy.dev/org/. If a Moochy button or badge is already there, do not add another; replace it only if the maintainer asked for a different style.
3. Where. If the README has a row of badges near the top (images linking to CI, coverage, package versions), add the button at the end of that row, on the same line or the same block, matching how the others are written (Markdown next to Markdown, HTML next to HTML). If there are no badges, add it on its own line right after the title (the first # heading or the ==== title), with one blank line before and after.
4. Keep everything else as it is. Do not reorder, reformat, or remove existing badges, and do not touch other files.
5. Commit only the README change, for example: docs: add a "Donate tokens" button (Moochy).

5. Check#

Open the image address in a browser or run curl -s -o /dev/null -w '%{http_code}\n' "<image address>": 200 means the image renders. 400 means an option is wrong (the image then reads "invalid button options"). A project that is not registered gets a "project not found" badge, also with 200 so README image proxies such as GitHub's still show it: check registration with the projects API (step 1).

button.svg reference#

https://moochy.dev/p/<provider>/<path>/button.svg is the image and …/donate is where it links (for GitHub also the short form /p/<owner>/<name>/…). Query parameters are optional; these are all the accepted ones:

Rules, enforced by the server:

• Any other parameter, a parameter given twice, a value not listed above, or a query longer than 256 bytes makes the server answer 400 with an image that reads "invalid button options". Tracking parameters such as utm_source therefore break the button.
• Parameter order does not matter. The studio leaves out defaults and writes the rest in alphabetical order.
• The image is cached for a day by the server and by GitHub's image proxy. A changed option shows within that time; a new address (different options) shows at once.

Organisations#

A GitHub organisation or a GitLab group claimed on Moochy has its own button: a donation to the organisation serves every project its owner chose (Donate to an organisation). Use it in the organisation's profile README, or in a project README when the maintainer asks for the organisation's button instead of the project's.

Personal accounts are not organisations: a personal profile README uses the button of one of the person's projects.

Check and get the addresses (ORG is acme on GitHub; group or group/subgroup on GitLab):

curl -fsS "https://moochy.dev/api/v1/orgs/github/ORG"

{"org_id": "o_01J…", "path": "github/acme", "claimed": true, "repos": [{"repo_id": "r_01J…", "slug": "github/acme/api"}], "donate_url": "https://moochy.dev/org/github/acme/donate", "button_url": "https://moochy.dev/org/github/acme/button.svg"}

Use button_url and donate_url exactly as returned. A 404 ({"error":"not_found"}) means the organisation is not on Moochy: do not add the button, and tell the maintainer what is in Not on Moochy yet. An empty repos list is fine: donations start serving once the owner adds a project.

As for projects, GitLab actions come after /-/. The organisation path always starts with github/ or gitlab/; there is no short form. The snippets of step 3, the query parameters, the placement rules of step 4 and the check of step 5 are the same. For example:

[![Donate tokens](https://moochy.dev/org/github/acme/button.svg)](https://moochy.dev/org/github/acme/donate)

moochy button prints project buttons only (moochy button --chart --org prints the organisation's chart); the organisation owner finds this snippet, with a copy button, in Organisation settings → Donate button.

People#

A maintainer who claimed their own GitHub or GitLab profile can be sponsored: a sponsorship pays for that person's own requests on the public repos they maintain (Sponsor a person). Their button goes in their personal profile README (GitHub: README.md of the repository named like the user, LOGIN/LOGIN; GitLab: the README.md of the project named like the user, USERNAME/USERNAME).

Check first and get the addresses with curl -fsS "https://moochy.dev/api/v1/people/github/LOGIN" (or …/people/gitlab/USERNAME): the same shape as the organisations API, and 404 means the person has not claimed their profile, so do not add the button. Use button_url and donate_url exactly as returned. Snippets, options and placement are those of steps 3 to 5.

Showcase charts#

Next to the button, a project, an organisation or a person can show a live chart of the tokens donated to it and used by it. It is an image, so it works in GitHub and GitLab READMEs like the button, and updates by itself (every five minutes at most). It shows totals per day only: never a donor, never an amount per donor.

Addresses#

The chart links to the page (not to /donate), where visitors see the whole picture and the Donate button. The GitHub short form (/p/OWNER/NAME/chart.svg) works too. An organisation's chart sums the projects its donations serve.

chart.svg options#

All optional; the same rules as the button (any other key, a key given twice, or a value not listed answers 400 with an image reading "invalid chart options"):

A project that is not on Moochy, or not public, gets one neutral "not on moochy" image instead of a chart (HTTP 200, so README image proxies such as GitHub's still show it).

Snippets#

moochy button --chart prints them for you, offline, with the same options (--metric, --series, --kind, --period, --theme, --size, --label, --goal, --total) and --format markdown|html|rst|iframe. Without --repo it reads the git remote, like moochy button; --org ORG and --person PERSON print the organisation's or the person's chart.

moochy button --chart                                             # this repository, Markdown
moochy button --chart --kind bars --period 90d --metric dollars --goal --total
moochy button --chart --format html                               # light and dark with <picture>
moochy button --chart --org github/acme --format iframe           # the card, for a website
moochy button --chart --person github/alice --kind sparkline --size s

Markdown (GitHub, GitLab):

[![Tokens donated and used on Moochy](https://moochy.dev/p/github/tinyhttp/arrow/chart.svg)](https://moochy.dev/p/github/tinyhttp/arrow)

HTML, light and dark (GitHub; the <source> gets theme=dark):

<a href="https://moochy.dev/p/github/tinyhttp/arrow">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://moochy.dev/p/github/tinyhttp/arrow/chart.svg?theme=dark">
    <img alt="Tokens donated and used on Moochy" src="https://moochy.dev/p/github/tinyhttp/arrow/chart.svg">
  </picture>
</a>

GitLab project, with options (/-/ before the action):

[![Tokens donated and used on Moochy](https://moochy.dev/p/gitlab/group/sub/project/-/chart.svg?goal=1&kind=bars&metric=dollars&period=90d&total=1)](https://moochy.dev/p/gitlab/group/sub/project)

Organisation (its profile README):

[![Tokens donated and used on Moochy](https://moochy.dev/org/github/acme/chart.svg)](https://moochy.dev/org/github/acme)

reStructuredText:

.. image:: https://moochy.dev/p/github/tinyhttp/arrow/chart.svg?metric=dollars
   :target: https://moochy.dev/p/github/tinyhttp/arrow
   :alt: Tokens donated and used on Moochy

Card for a website (not for READMEs: GitHub and GitLab strip iframes). No script, no cookie, one link that opens the project page in a new tab:

<iframe src="https://moochy.dev/org/github/acme/card" title="Tokens donated and used on Moochy" width="480" height="240" style="border:0" loading="lazy"></iframe>

Card sizes: s 320×160, m 480×240, l 640×320; sparklines 320×40, 480×60, 640×80.

Put the chart in the README right below the button row or in a "Support" section, never instead of the button; the placement rules of step 4 apply. Keep the alt text (it is what screen readers announce); the image also carries its own text summary.

The showcase studio#

https://moochy.dev/button is the showcase studio: tab Button and tab Chart. Pick a project or organisation you can see, set every option above with a live preview in light and dark side by side, and copy the Markdown, HTML, reStructuredText or iframe snippet. The URLs are the canonical ones above (/-/ on GitLab), exactly what moochy button --chart prints.

Not on Moochy yet#

If the project is not registered, give the maintainer this message (replace PATH with the path from step 1):

Moochy lets people donate LLM tokens to this project from their own API accounts. To accept donations: sign in at https://moochy.dev/claim with the GitHub or GitLab account that administers PATH, register the repository, then confirm on your own machine with the Moochy app: moochy owner init (once) and moochy claim PATH. After that, the "Donate tokens" button can go in the README. Guide: https://moochy.dev/docs/maintainer

For an organisation (ORG as github/acme or gitlab/group/subgroup):

To accept token donations for the whole organisation: sign in at https://moochy.dev/claim with an account that owns ORG (GitHub: an organisation admin; GitLab: a group Owner), choose Organisation, then confirm on your own machine with the Moochy app: moochy claim --org ORG, and add the projects it funds with moochy org add PROJECT --org ORG. Guide: https://moochy.dev/docs/organisations

Do not register the project or the organisation yourself, and do not run moochy commands that sign anything on the maintainer's behalf: claiming needs the maintainer's own owner key and confirmation.

What not to do#

• No secrets. The button needs no API key, token, password, or Moochy account. Never put one in a README, a URL, or a commit, and never ask the maintainer for one to add the button.
• No tracking. Do not add analytics or utm_* parameters, redirects, or link shorteners. Moochy does not track readers: it sees requests from GitHub's image proxy, not from visitors.
• No scripts or embeds in a README. No JavaScript, iframes (the chart card is for websites), or inline SVG copies of the button or chart.
• No donations or settings changes. Adding a button never creates a donation, signs in, changes CI, or edits Moochy settings.
• No other files. Only the README changes.

The studio#

People can also build the button by hand: on moochy.dev, open the project and choose Donate button (or go to https://moochy.dev/button, tab Button). Pick the label, style, theme, and size, see a live preview, and copy the Markdown or HTML. It produces exactly the snippets above. Tab Chart builds the showcase chart.

For maintainers: tell your agents#

Add this to your repository's AGENTS.md, CLAUDE.md, or similar instructions file, so coding agents know about the button and keep it intact:

## Moochy donate button

This project accepts LLM token donations through Moochy (https://moochy.dev).
- The README shows a "Donate tokens" button linking to the project's Moochy page (https://moochy.dev/p/…/donate).
  Keep it when you edit the README; do not duplicate it, change its address, or add tracking parameters.
- To add or change it, follow https://moochy.dev/docs/donate-button.md exactly.
- Never put API keys or tokens in the README or in commits.

This page as Markdown: /docs/donate-button.md · for AI agents: /llms.txt