Shield
Moth DocsProtocol
With Shield on, the emails, phone numbers, card numbers, secrets and wallet addresses in a prompt leave Moth as placeholders, and the real values come back in the reply.
Shield is off unless you turn it on. When it is on, Moth finds these values in a chat request and swaps each one for a placeholder before the request leaves Moth, so the model's host reads [EMAIL_1] where you wrote an address. On the way back, every placeholder in the reply is turned back into its value, streamed or not, so your app reads its own text again.
What it swaps
[EMAIL_1]Any address with a name, an @ and a domain[PHONE_1]A number written with + and a country code, or in the forms (555) 123-4567 and 555-123-4567[CARD_1]13 to 19 digits, run together or in groups, that start as a card network's do and pass the card checksum[SECRET_1]API keys in known formats, such as sk-, moth_, ghp_, AWS and Google keys and Slack and Stripe tokens, and private key blocks[WALLET_1]0x followed by 40 hex characters, and bc1 addressesEach kind is numbered in the order its values first appear, and the same value keeps the same placeholder everywhere in the request, so a conversation that names one address ten times sends [EMAIL_1] ten times. When anything was swapped, a short instruction asks the model to keep the placeholders exactly as written. You don't pay for its tokens.
Turn it on for one call
Send the moth-shield header with on. off turns it off for one call on a key that has it on, and any other value is refused with 400 before anything is held.
curl https://api.runmoth.si/v1/chat/completions \ -H "Authorization: Bearer $MOTH_API_KEY" \ -H "Content-Type: application/json" \ -H "moth-shield: on" \ -d '{"model":"gemini-3.8-flash","messages":[{"role":"user","content":"Draft a reply to ana@example.com"}]}'
Turn it on for a key
In Moth Console, open a key under API keys, choose Edit and set Shield to On, or set it when you make the key. Every call made with that key is then shielded unless it sends moth-shield: off. Through the API, send shield: true when you make or change a key.
What the reply says
Every shielded reply carries a moth-shield header that counts what was swapped and never shows a value, such as email=1, card=1, or none when the request held nothing to swap.
Where it applies
- Chat models on
/chat/completionsand/messages, streamed or not, including the text of tool calls and tool results. - Not Sealed models, whose requests are already sealed from Moth, and not image, video or music prompts, which are sent as written.
- Thinking blocks are passed on as the model wrote them, since their text is signed, so a placeholder inside one stays a placeholder.
- Tool definitions and output schemas are sent as written.
What Shield doesn't find. Shield matches fixed formats, so it doesn't find names, street addresses or anything that needs context to recognise. A value written in an unusual form can pass through as written. The swap table lives in that one request's memory and is gone when the reply ends, and nothing about it is logged or stored.