Saltar al contenido principal

Cotiza y luego compra con max_price_trx

Una app conectada debe pasar max_price_trx a buy_energy y buy_bandwidth. Sin él, la llamada falla con MAX_PRICE_REQUIRED: el límite diario necesita saber lo máximo que puede costar una llamada.
  1. Llama a quote_energy (o quote_bandwidth) con el volumen y la duración.
  2. Muestra al usuario el total_trx de la cotización.
  3. Llama a buy_energy con el mismo volumen y duración y max_price_trx = el total_trx de la cotización.
Si el precio sube por encima de max_price_trx, la compra se rechaza con PRICE_CHANGED y no se cobra nada. Vuelve a cotizar y pregunta al usuario. Para una clave API max_price_trx es opcional, pero lo recomendamos por el mismo motivo.

Claves de idempotencia

Las herramientas que crean algo aceptan idempotency_key: la cabecera Idempotency-Key de su ruta. Genera un UUID nuevo para cada acción nueva y reutilízalo cuando reintentes la misma acción tras un timeout o una respuesta perdida: el servidor devuelve el primer resultado en lugar de cobrar otra vez. Una clave dura 24 horas y tiene como máximo 64 caracteres. La misma clave con una solicitud distinta se rechaza con IDEMPOTENCY_KEY_REUSED; una clave cuya primera solicitud sigue en curso responde IDEMPOTENT_REQUEST_IN_PROGRESS: espera y reintenta con la misma clave.

Límite diario de gasto

Cada conexión puede gastar una cantidad fija en cualquier periodo de 24 horas: 100 TRX, salvo que el usuario haya elegido otra cantidad en la pantalla de consentimiento o en Aplicaciones conectadas. Solo el propietario de la cuenta puede quitar el límite.
  • Antes de una llamada que gasta, el servidor reserva lo máximo que puede costar: max_price_trx más la activación de una dirección nueva en las compras, el precio en Smart Mode, paquetes, activaciones y planes de Node API, el importe en un stake.
  • Tras la llamada, la reserva pasa a ser el importe real, o se libera si no se cobró nada. Si el resultado es desconocido (un timeout), la reserva se mantiene 24 horas: ante la duda, el límite rechaza.
  • El gasto que se ejecuta solo (recurring) queda fuera del límite.
  • Aplicaciones conectadas en el panel muestra lo que gastó cada app en las últimas 24 horas.
Una llamada que no cabe falla con AGENT_SPEND_CAP:
El reintento de una compra cuya respuesta se perdió vuelve a reservar su importe. Cerca del límite, consulta list_orders antes de reintentar: puede que la primera llamada se haya completado.

Origen del pedido

Los pedidos hechos por una app conectada llevan "source": "agent", en get_order, list_orders y el webhook order.updated. Los pedidos hechos con una clave API llevan "source": "api".

Códigos de error

Por MCP, un error llega como resultado de herramienta con isError: true:
Por REST, el mismo código llega en el formato de error estándar. Todos los demás códigos son los de la API REST; consulta Errores. Un token caducado o revocado recibe HTTP 401 con WWW-Authenticate: Bearer ... error="invalid_token" en la propia solicitud a /mcp; los clientes MCP entonces renuevan el token o piden al usuario que vuelva a iniciar sesión.