> ## 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.

# Claves de agente: permite que un agente de IA realice comercio acotado

> Otorga a un agente autónomo una clave limitada y con tope de gasto que puede crear enlaces de pago reales por MCP — distinta de las claves de IA de solo lectura usadas para analítica.

Una **clave de agente** permite que un agente autónomo realice una acción de comercio real en tu nombre — crear un enlace de pago cobrable para que un comprador pague — dentro de límites estrictos que tú defines. Es una capacidad distinta de las [claves de IA](/ai/bring-your-own-ai) usadas para conectar un asistente a tu analítica y datos de integración.

<Warning>
  **Las claves de agente no son claves de IA.** Una [clave de IA](/ai/bring-your-own-ai) (`ai_live_…` / `ai_sandbox_…`) es de solo lectura y solo alcanza datos de sandbox — nunca puede mover dinero. Una **clave de agente** (`agent_live_…` / `agent_sandbox_…`) puede crear un enlace de pago real y cobrable en producción, sujeto a los límites de gasto que configures. Elige la clave de IA para "dejar que un asistente analice mis pagos"; elige la clave de agente para "dejar que un agente transaccione en mi nombre."
</Warning>

## Por qué usarla

* **Acotada por diseño.** Una clave de agente no puede hacer nada hasta que le otorgues explícitamente capacidades — la concesión por defecto es de solo lectura. El acceso que mueve dinero (`create_payment_link`) es opcional y debe activarse.
* **Topes de gasto estrictos.** Cada clave tiene un tope por enlace y un tope diario total, en una sola moneda. Ambos se aplican de forma atómica en el servidor antes de crear un enlace — un agente no puede excederlos, ni siquiera con llamadas concurrentes.
* **Un humano completa el pago.** `create_payment_link` devuelve una URL de checkout alojado. El agente nunca posee datos de tarjeta y nunca finaliza un cobro por sí mismo — el comprador paga a través del enlace.
* **Un conjunto de herramientas fijo y cerrado.** Hoy existen exactamente cuatro herramientas detrás de una clave de agente: crear un enlace, consultar el estado de un enlace, listar enlaces y consultar el estado de un pago. No hay forma de otorgarle a una clave de agente acceso a ningún otro endpoint.
* **Estructuralmente separada de una clave secreta.** Una clave de agente nunca puede autenticarse como tu clave privada de API. Se resuelve mediante su propia ruta de código y es rechazada por cualquier otro endpoint de la API.
* **Auditada.** Cada llamada a herramienta que hace una clave de agente — nombre de la herramienta, argumentos, resultado — queda registrada.

## Crear una clave de agente

En el dashboard de Therius, ve a **Developers → Agent keys**:

<Steps>
  <Step title="New agent key">
    Haz clic en **New agent key**. Dale una etiqueta y elige el entorno (**producción** o **sandbox**).
  </Step>

  <Step title="Otorgar capacidades">
    Selecciona cuáles de las cuatro herramientas puede llamar esta clave. Deja `create_payment_link` sin marcar para emitir una clave de solo lectura.
  </Step>

  <Step title="Definir límites de gasto">
    Si otorgas `create_payment_link`, define un **tope por enlace**, un **tope diario total** y la **moneda** en la que se denominan. El tope por enlace no puede superar el tope diario.
  </Step>

  <Step title="Copiar la clave">
    La clave completa (`agent_live_…` o `agent_sandbox_…`) se muestra **una sola vez** y no se puede recuperar después. Guárdala en un gestor de secretos.
  </Step>
</Steps>

Puedes revocar una clave en cualquier momento desde la misma página — la revocación es inmediata.

## Conectar un cliente MCP

Apunta cualquier cliente compatible con MCP al endpoint que se muestra en la 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>

El endpoint habla JSON-RPC 2.0. Tu cliente descubre las herramientas disponibles mediante `tools/list` — solo verá las herramientas que las capacidades de tu clave permitan.

<Note>
  Este es un endpoint separado del servidor MCP de [Bring Your Own AI](/ai/bring-your-own-ai) (`ai.therius.io`). Una clave de agente solo se autentica contra `POST /v1/mcp` en la API de pagos; nunca es aceptada por el servidor MCP de claves de IA, y una clave de IA nunca es aceptada aquí.
</Note>

## Herramientas

| Herramienta               | Hace                                                                                                                                                                    | Capacidad                 | Modifica datos |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -------------- |
| `create_payment_link`     | Crea un enlace de pago de un solo uso y cobrable para que un comprador pague. Se verifica y reserva contra los límites de gasto de esta clave antes de crear el enlace. | `create_payment_link`     | Sí             |
| `get_payment_link_status` | Consulta el estado de un enlace de pago creado por esta clave.                                                                                                          | `get_payment_link_status` | No             |
| `list_payment_links`      | Lista los enlaces de pago de este comercio, opcionalmente filtrados por estado.                                                                                         | `list_payment_links`      | No             |
| `get_payment_status`      | Consulta el estado de un pago por ID o código de pago, limitado al comercio de esta clave.                                                                              | `get_payment_status`      | No             |

Una clave se emite con las tres de solo lectura (`get_payment_link_status`, `list_payment_links`, `get_payment_status`) por defecto, a menos que otorgues explícitamente `create_payment_link`.

### Argumentos de `create_payment_link`

| Argumento         | Tipo    | Requerido | Notas                                                                                                                                                |
| ----------------- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`          | integer | Sí        | Unidades menores (por ejemplo, centavos). Se verifica contra el tope por enlace y el gasto diario restante de la clave.                              |
| `currency`        | string  | Sí        | Código ISO 4217. Debe coincidir con la moneda configurada en los límites de gasto de la clave — una solicitud en cualquier otra moneda es rechazada. |
| `title`           | string  | No        | Se muestra en la página de checkout alojado.                                                                                                         |
| `description`     | string  | No        | Se muestra en la página de checkout alojado.                                                                                                         |
| `reference`       | string  | No        | Tu propia referencia de pedido.                                                                                                                      |
| `expires_in_days` | integer | No        | El valor por defecto es 7.                                                                                                                           |

Una llamada exitosa devuelve el `id` del enlace, su `url` de checkout alojado y `remaining_today` — el gasto aún disponible dentro del tope diario de la clave.

## Alcance y seguridad

* **Conjunto de herramientas fijo.** Las cuatro herramientas de arriba son toda la superficie que una clave de agente puede alcanzar. No hay forma de otorgarle a una clave de agente acceso a ningún otro endpoint, y el conjunto no puede crecer sin un cambio de código de Therius.
* **El gasto se reserva de forma atómica.** La verificación del tope por enlace y del tope diario y el incremento del gasto ocurren en una sola operación de base de datos — una verificación nunca puede pasar mientras una llamada concurrente también pasa y juntas superan el tope diario.
* **Con moneda fija.** `create_payment_link` solo acepta la moneda configurada en la clave. No hay gasto entre monedas.
* **Limitada a un comercio.** Una clave de agente se resuelve a exactamente un comercio. `list_payment_links` y `get_payment_status` nunca devuelven datos de otro comercio; una búsqueda que no coincide devuelve "no encontrado," no un error de permisos, así que una clave ni siquiera puede confirmar que existe el pago de otro comercio.
* **Nunca un sustituto de la clave secreta.** Una clave de agente se resuelve mediante su propia ruta de autenticación, completamente separada de tu clave privada de API (`prv_production_…` / `prv_sandbox_…`). Es rechazada por `/payment/*` y por cualquier otro endpoint fuera de `/v1/mcp`.
* **Limitada por entorno.** Las claves `agent_live_` alcanzan producción; las claves `agent_sandbox_` alcanzan sandbox. No hay cruce entre ambos.
* **Auditada.** Cada llamada a herramienta — nombre de la herramienta, argumentos y resultado — se escribe en el registro de auditoría.