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.
- Llama a
quote_energy(oquote_bandwidth) con el volumen y la duración. - Muestra al usuario el
total_trxde la cotización. - Llama a
buy_energycon el mismo volumen y duración ymax_price_trx= eltotal_trxde la cotización.
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 aceptanidempotency_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_trxmá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.
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 conisError: true:
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.