create_topup_link

Get a secure payment link the account owner can use to add AI credits.

                    USAGE INSTRUCTIONS FOR LLM:
                    Returns a URL to a page where a human can pay with the card already on file or
                    enter a new one. You do NOT need to wait for something to fail first — ask for
                    the link the moment more credit is the obvious next step. Share the URL with the
                    account owner; you cannot pay on their behalf.

                    WHEN TO USE THIS TOOL:
                    - The balance is low or negative and the user wants to fix it now
                    - An audience or other work is about to cost more than the balance covers
                    - The user asks how to add credit, buy credits, or pay
                    - Any tool refused for lack of credit and you did not get a link with it

                    This tool keeps working when the balance is exhausted — being out of credit is
                    exactly when it is needed.

                    CALL THIS ONCE AND SHARE THE URL YOU GET. Each call issues a NEW link and
                    INVALIDATES any previous one for the account, because only one live payment
                    capability may exist at a time. So if you mint a second link after sharing the
                    first, the URL the account owner is holding stops working. Do not call it again
                    to "check" or "refresh" — re-read your earlier result instead.

                    AFTER SHARING IT: payment settles ASYNCHRONOUSLY. Poll `get_credit_balance`
                    every 20-30 seconds, not continuously, and resume work once the balance covers
                    what you need.

                    EXPECTED RESPONSE FORMAT:
                    {
                      "url": "https://agency-stage.metadata.io/payment/<token>",
                      "expires_at": "2026-08-11T18:58:00Z",
                      "max_amount_usd": 0,       // ceiling on this link; 0 means none
                      "account_id": "1234",
                      "balance_usd": -12.5       // the balance right now, for context
                    }

                    On failure returns {"error": "..."} — say that a link could not be created and
                    point the user at the Metadata app to add credit instead. Never invent a URL.