The MENTA API

Get a key in ten seconds

In the server you want to build on, type:

$apikey new my-bot

MENTA sends the key to your DMs. It is shown once. Store it the way you would store a password — in an environment variable, never in front-end code and never in a repo.

curl https://menta.tips/v1/me \
  -H "Authorization: Bearer menta_live_..."

Keys are for the server owner and anyone with Manage Server. Manage them with $apikey, see what yours has been doing with $apikey calls, and kill one instantly with $apikey revoke menta_live_ab12cd.

What a key can and cannot do

Three more limits, all enforced before any handler runs:

• It spends your balance and nobody else's. There is no from parameter anywhere in the API. The account is fixed when the key is minted.
• It works in one server. A key made in a ten-member server cannot post into a ten-thousand-member one, whatever channel id it is handed.
• It can have a daily ceiling. Set one when you create the key ($apikey new my-bot 50000 CHAD) and a leaked key is a bad day rather than an empty jar.

Rate limit: 120 requests a minute, burstable to 40 at once, per key. Every response carries x-ratelimit-remaining.

Endpoints

Reading

Writing

Tip someone for doing something

curl -X POST https://menta.tips/v1/tips \
  -H "Authorization: Bearer $MENTA_KEY" \
  -H "Idempotency-Key: level-up-8412" \
  -H "Content-Type: application/json" \
  -d '{"to": "685908488203010088", "asset": "CHAD", "amount": "500"}'

{
  "ok": true,
  "transfer_id": "48213",
  "asset": { "symbol": "CHAD", "chain": "base", "decimals": 18 },
  "recipients": ["685908488203010088"],
  "per_recipient": { "amount": "500", "amount_base": "500000000000000000000" },
  "total": { "amount": "500", "amount_base": "500000000000000000000" }
}

to also takes an array — one call, up to 100 members, each getting amount.

Drop a pot into a channel

curl -X POST https://menta.tips/v1/drops \
  -H "Authorization: Bearer $MENTA_KEY" \
  -H "Idempotency-Key: raid-win-2211" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": "1543978711479488523", "asset": "CHAD",
       "amount": "25000", "minutes": 10, "note": "You cleared the raid."}'

MENTA posts the piñata with a claim button and splits the pot between everyone who hits it before the timer. Nobody claims? It comes back to you automatically.

Try it right now

Every tip is addressed to a Discord user id. Connect below and this page fills the example in with yours — that is the exact value your code puts in to.

Telegram, your website, anywhere

MENTA pays Discord accounts. Your Telegram bot knows Telegram ids; your website knows its own user ids. Account links join the two, once, per person.

curl -X POST https://menta.tips/v1/links \
  -H "Authorization: Bearer $MENTA_KEY" \
  -H "Idempotency-Key: link-99887" \
  -d '{"external_id": "telegram:99887", "label": "@ada"}'

{ "status": "pending",
  "link_url": "https://menta.tips/link/8Ff2xQ...",
  "expires_in_hours": 24 }

Then pay them by your id — no Discord ids anywhere in your code:

curl -X POST https://menta.tips/v1/tips \
  -H "Authorization: Bearer $MENTA_KEY" \
  -H "Idempotency-Key: quest-4417" \
  -d '{"to_external": "telegram:99887", "asset": "CHAD", "amount": "500"}'

A link is a forwarding address, not a login

Connecting lets you pay that person. It gives you nothing else: no reading their balance, no spending it, no acting as them. There is no operation in MENTA where a key takes from an account that linked to it, which is why the consent screen can promise that plainly.

Working examples

• telegram-bot.js — a Telegram bot with /connect, /tip and /balance. No dependencies, about 100 lines, runs on Node 18+.
• website-rewards.js — a website that connects users, rewards them, and verifies incoming webhooks.
• the whole thing on GitHub — these two plus webhook verification in JS and Python, a zero-dependency Node client, and openapi.yaml for Postman or a code generator. MIT licensed.

Amounts are strings. Always.

Sending works the same way: pass "amount": "1250.5" or, if you already hold base units, "amount_base": "1250500000".

Retries cannot double-send

Every write needs an Idempotency-Key header — any string unique to that attempt. Retry with the same one and you get the original response back, marked "replayed": true. Nothing sends twice.

This is not optional and it is not decoration: a request that times out has not necessarily failed, and "did my tip go through?" is a question your code should never have to guess at. Use something meaningful — an event id, a message id, a job id.

Webhooks

Point an https endpoint at MENTA and hear about things as they happen — in your server, and on your own account.

curl -X POST https://menta.tips/v1/webhooks \
  -H "Authorization: Bearer $MENTA_KEY" \
  -H "Idempotency-Key: hook-1" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/menta", "events": ["tip.created", "drop.claimed"]}'

Leave events out to get everything. The response carries a secret — shown once, like a key.

Verify the signature

Every delivery carries x-menta-signature: t=1788193268,v1=<hex>, an HMAC-SHA256 over timestamp.body using your webhook secret. Check it before you trust the body, and reject a timestamp older than five minutes — that is what stops someone replaying a delivery they captured.

// Node
import crypto from "node:crypto";

function verify(secret, header, rawBody) {
  const p = Object.fromEntries(header.split(",").map(s => s.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${p.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}

Use the raw body, not a re-serialised object — re-encoding changes the bytes and the signature will not match.

A delivery that fails is retried after 30s, 2m, 10m, 1h and 6h. Answer with any 2xx as soon as you have the payload; do your work afterwards.

Errors

Always the same shape, always a sentence you can show a human.

{ "error": { "code": "insufficient_funds",
            "message": "You don't have enough CHAD for that." } }