> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chaves de agente: permita que um agente de IA realize comércio limitado

> Dê a um agente autônomo uma chave limitada e com teto de gasto que pode criar links de pagamento reais via MCP — diferente das chaves de IA somente leitura usadas para analytics.

Uma **chave de agente** permite que um agente autônomo realize uma ação real de comércio em seu nome — criar um link de pagamento cobrável para um comprador pagar — dentro de limites rígidos que você define. É uma capacidade diferente das [chaves de IA](/ai/bring-your-own-ai) usadas para conectar um assistente aos seus dados de analytics e integração.

<Warning>
  **Chaves de agente não são chaves de IA.** Uma [chave de IA](/ai/bring-your-own-ai) (`ai_live_…` / `ai_sandbox_…`) é somente leitura e alcança apenas dados de sandbox — nunca pode movimentar dinheiro. Uma **chave de agente** (`agent_live_…` / `agent_sandbox_…`) pode criar um link de pagamento real e cobrável em produção, sujeito aos limites de gasto que você configurar. Escolha a chave de IA para "deixar um assistente analisar meus pagamentos"; escolha a chave de agente para "deixar um agente transacionar em meu nome."
</Warning>

## Por que usar

* **Limitada por design.** Uma chave de agente não pode fazer nada até que você conceda explicitamente capacidades a ela — a concessão padrão é somente leitura. O acesso que movimenta dinheiro (`create_payment_link`) é opcional.
* **Tetos de gasto rígidos.** Toda chave tem um teto por link e um teto diário total, em uma única moeda. Ambos são aplicados de forma atômica no servidor antes de criar um link — um agente não consegue ultrapassá-los, nem mesmo em chamadas concorrentes.
* **Um humano ainda completa o pagamento.** `create_payment_link` retorna uma URL de checkout hospedado. O agente nunca detém dados de cartão e nunca finaliza uma cobrança sozinho — o comprador paga através do link.
* **Um conjunto fixo e fechado de ferramentas.** Hoje existem exatamente quatro ferramentas por trás de uma chave de agente: criar um link, consultar o status de um link, listar links e consultar o status de um pagamento. Não há como conceder a uma chave de agente acesso a qualquer outro endpoint.
* **Estruturalmente separada de uma chave secreta.** Uma chave de agente nunca pode se autenticar como a sua chave privada de API. Ela é resolvida por meio de seu próprio caminho de código e é rejeitada por qualquer outro endpoint da API.
* **Auditada.** Toda chamada de ferramenta feita por uma chave de agente — nome da ferramenta, argumentos, resultado — é registrada.

## Criar uma chave de agente

No painel do Therius, vá em **Developers → Agent keys**:

<Steps>
  <Step title="New agent key">
    Clique em **New agent key**. Dê um rótulo e escolha o ambiente (**produção** ou **sandbox**).
  </Step>

  <Step title="Conceder capacidades">
    Selecione quais das quatro ferramentas essa chave pode chamar. Deixe `create_payment_link` desmarcado para emitir uma chave somente leitura.
  </Step>

  <Step title="Definir limites de gasto">
    Se você conceder `create_payment_link`, defina um **teto por link**, um **teto diário total** e a **moeda** em que eles são denominados. O teto por link não pode exceder o teto diário.
  </Step>

  <Step title="Copiar a chave">
    A chave completa (`agent_live_…` ou `agent_sandbox_…`) é exibida **uma única vez** e não pode ser recuperada depois. Guarde-a em um gerenciador de segredos.
  </Step>
</Steps>

Revogue uma chave a qualquer momento na mesma página — a revogação é imediata.

## Conectar um cliente MCP

Aponte qualquer cliente compatível com MCP para o endpoint mostrado na página **Developers → Agent keys**:

<CodeGroup>
  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http therius-agent https://api.therius.io/v1/mcp \
    --header "Authorization: Bearer <your-agent-key>"
  ```

  ```json Claude Desktop / Cursor (mcp.json) theme={"dark"}
  {
    "mcpServers": {
      "therius-agent": {
        "url": "https://api.therius.io/v1/mcp",
        "headers": { "Authorization": "Bearer <your-agent-key>" }
      }
    }
  }
  ```
</CodeGroup>

O endpoint fala JSON-RPC 2.0. Seu cliente descobre as ferramentas disponíveis via `tools/list` — ele só verá as ferramentas que as capacidades da sua chave permitirem.

<Note>
  Este é um endpoint separado do servidor MCP do [Bring Your Own AI](/ai/bring-your-own-ai) (`ai.therius.io`). Uma chave de agente só se autentica contra `POST /v1/mcp` na API de pagamentos; ela nunca é aceita pelo servidor MCP de chaves de IA, e uma chave de IA nunca é aceita aqui.
</Note>

## Ferramentas

| Ferramenta                | Faz                                                                                                                                                                    | Capacidade                | Modifica dados |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -------------- |
| `create_payment_link`     | Cria um link de pagamento de uso único e cobrável para um comprador pagar. É verificada e reservada contra os limites de gasto desta chave antes de o link ser criado. | `create_payment_link`     | Sim            |
| `get_payment_link_status` | Consulta o status de um link de pagamento criado por esta chave.                                                                                                       | `get_payment_link_status` | Não            |
| `list_payment_links`      | Lista os links de pagamento deste lojista, opcionalmente filtrados por status.                                                                                         | `list_payment_links`      | Não            |
| `get_payment_status`      | Consulta o status de um pagamento por ID ou código de pagamento, limitado ao lojista desta chave.                                                                      | `get_payment_status`      | Não            |

Uma chave é emitida com as três somente leitura (`get_payment_link_status`, `list_payment_links`, `get_payment_status`) por padrão, a menos que você conceda explicitamente `create_payment_link`.

### Argumentos de `create_payment_link`

| Argumento         | Tipo    | Obrigatório | Notas                                                                                                                                       |
| ----------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`          | integer | Sim         | Unidades menores (por exemplo, centavos). Verificado contra o teto por link e o gasto diário restante da chave.                             |
| `currency`        | string  | Sim         | Código ISO 4217. Deve corresponder à moeda configurada nos limites de gasto da chave — uma solicitação em qualquer outra moeda é rejeitada. |
| `title`           | string  | Não         | Exibido na página de checkout hospedado.                                                                                                    |
| `description`     | string  | Não         | Exibido na página de checkout hospedado.                                                                                                    |
| `reference`       | string  | Não         | Sua própria referência de pedido.                                                                                                           |
| `expires_in_days` | integer | Não         | O padrão é 7.                                                                                                                               |

Uma chamada bem-sucedida retorna o `id` do link, sua `url` de checkout hospedado e `remaining_today` — o gasto ainda disponível dentro do teto diário da chave.

## Escopo e segurança

* **Conjunto fixo de ferramentas.** As quatro ferramentas acima são toda a superfície que uma chave de agente pode alcançar. Não há como conceder a uma chave de agente acesso a qualquer outro endpoint, e o conjunto não pode crescer sem uma mudança de código do Therius.
* **O gasto é reservado atomicamente.** A verificação do teto por link e do teto diário e o incremento do gasto ocorrem em uma única operação de banco de dados — uma verificação nunca pode passar enquanto uma chamada concorrente também passa e juntas excedem o teto diário.
* **Com moeda travada.** `create_payment_link` só aceita a moeda configurada na chave. Não há gasto entre moedas.
* **Limitada a um lojista.** Uma chave de agente é resolvida para exatamente um lojista. `list_payment_links` e `get_payment_status` nunca retornam dados de outro lojista; uma busca que não corresponde retorna "não encontrado," não um erro de permissão, então uma chave nem consegue confirmar que o pagamento de outro lojista existe.
* **Nunca um substituto da chave secreta.** Uma chave de agente é resolvida por meio de seu próprio caminho de autenticação, totalmente separado da sua chave privada de API (`prv_production_…` / `prv_sandbox_…`). Ela é rejeitada por `/payment/*` e por qualquer outro endpoint fora de `/v1/mcp`.
* **Vinculada ao ambiente.** Chaves `agent_live_` alcançam produção; chaves `agent_sandbox_` alcançam sandbox. Não há cruzamento entre eles.
* **Auditada.** Toda chamada de ferramenta — nome da ferramenta, argumentos e resultado — é registrada no log de auditoria.