Skip to main content
Agent payments are in preview. SolvaPay has to turn them on for your merchant account before agents can pay you. Until then, every paid call is refused. The API in solvapay.agents may change between minor releases.
With agent payments, an AI agent pays for each tool call from a budget its owner set up with SolvaPay. SolvaPay decides each call: it finds the customer, checks the owner’s spend policy, holds the estimate against the budget and balance, and asks the owner to approve when the policy says so. Your server authorizes each paid call before it runs and completes it at the cost your upstream reports.

Prerequisites

  • pip install 'solvapay[agents,mcp]' uvicorn
  • Agent payments turned on for your merchant account
  • These environment variables:

Serve a paid tool to agents

route.middleware(app) answers requests on /mcp that carry an agent token or agent key (agk_...), and passes every other request to your app. To keep serving signed-in customers on the same /mcp, pass your paid MCP server’s http_app() as the app. You can also call await route(request) from your own handler: it returns a response for an agent’s request, or None.

What happens on a paid call

  1. Identify. AgentLayer tells an agent’s credential from your own. AgentTokenVerifier checks agent tokens (ES256 JWTs) against SolvaPay’s keys at <issuer>/jwks.json. AgentKeyVerifier asks SolvaPay whose an agent key is and reuses the answer for 30 seconds.
  2. Authorize. AgentCalls sends the call’s item and estimate to SolvaPay. When the owner must approve, it waits up to max_wait_seconds (0 refuses at once). Keep it under your MCP client’s timeout, and the API client’s timeout above it.
  3. Run. Your run calls the upstream and returns a PaidToolRun with the upstream’s status, the reported cost as (amount, currency), and the result for the agent.
  4. Complete. SolvaPay settles the call at the reported cost. A status of 400 or above charges nothing. If run raises, the hold is released and nothing is charged.
PaidTool fields:

Refusals

A refused call is a tool error (isError: true). Its text is a sentence for the agent’s owner, and structuredContent.refusal.reason says which refusal it was, so an agent can act on it without parsing text: refusal_status(reason) gives the matching HTTP status if you serve agents outside MCP: 402, 422, 401 or 502.

Sign-in for hosts such as Claude and ChatGPT

By default, agents bring their own token or agent key. To let hosts sign in with SolvaPay’s agent OAuth, pass protected_resource=ProtectedResource(resource="https://research.example.com/mcp") to create_agent_mcp_route, and the same URL as resource= to AgentTokenVerifier. The route then serves the protected-resource document and challenges a paid call that has no token. free_tools= registers tools anyone can call, signed in or not.

Next steps