BroSettlement API – Habilidades para Agentes de IA

API de BroSettlement

Utilice el Swagger actual del entorno seleccionado como fuente de verdad. Producción es el valor por defecto:

• Interfaz de Swagger de Producción: https://brosettlement-api.brolabel.io/swagger-integration
• JSON de Swagger de Producción: https://brosettlement-api.brolabel.io/swagger-integration-json
• Interfaz de Swagger de Staging: https://brosettlement-staging-api.brolabel.io/swagger-integration#/
• JSON de Swagger de Staging: https://brosettlement-staging-api.brolabel.io/swagger-integration-json

Use producción a menos que el usuario seleccione explícitamente staging o que el skill de incorporación que lo invoca derive staging de app-staging.brolabel.io. Nunca mezcle credenciales, Swagger, puntos finales REST o WebSocket entre entornos.

Lea references/api.md antes de diseñar o modificar una integración.

Protocolo de credenciales

Prefiera una clave API existente. Pregunte únicamente por:

• el ID de la clave API;
• la ruta absoluta al archivo PEM Ed25519 privado que ya está almacenado en la máquina del usuario;
• la confirmación de que la clave tiene el ámbito requerido y que todos los ajustes necesarios que se muestran en la página de claves API están completos.

Nunca pida al usuario que pegue una clave privada, contraseña, JWT, código TOTP o token de sesión en el chat. No solicite la IP pública de salida del usuario ni llame a un servicio de descubrimiento de IP; dirija al usuario a la red actual y a las instrucciones de la lista de permitidos que se muestran en la página de claves API. Nunca inicie sesión en la Consola ni llame a puntos finales CRUD de claves API para crear, editar, rotar o revocar una clave. Si se requiere una nueva clave, genere un par Ed25519 local únicamente con la confirmación requerida, muestre solo la clave pública y dé al usuario instrucciones manuales para la Consola. Espere hasta que el usuario confirme que la creación de la clave, los ámbitos, la lista de permitidos y el estado activo están completos.

Cargue las credenciales existentes en tiempo de ejecución a través de BROSETTLEMENT_API_KEY_ID y BROSETTLEMENT_API_PRIVATE_KEY_FILE. Seleccione los puntos finales con BROSETTLEMENT_ENVIRONMENT=production|staging; un valor no establecido significa producción. No copie los valores de las credenciales en archivos fuente, mensajes, ejemplos generados o el historial del shell.

Flujo de trabajo

1. Prepare la CLI empaquetada y ejecute su comprobación automática de versión como se describe a continuación. Esto puede actualizar solo el ejecutable compilado de la CLI; nunca actualice SKILL.md, referencias, scripts o skills hermanos.
2. Use producción por defecto y dígalo explícitamente. Use staging solo cuando se haya seleccionado explícitamente o se haya derivado del nombre de host de la Consola de staging.
3. Obtenga el JSON de Swagger actual antes de responder preguntas sobre puntos finales, comandos, campos, enumeraciones, ámbitos o esquemas de error.
4. Identifique la operación exacta, el esquema de solicitud, el esquema de respuesta, el ámbito requerido, los encabezados de autenticación, el requisito de hash del cuerpo y el requisito de idempotencia.
5. Resuelva las credenciales a través del protocolo de credenciales y verifique los requisitos previos sin imprimir secretos.
6. Prepare un plan de solicitud redactado: entorno, método, destino exacto, ámbito, fuente del cuerpo, comportamiento de idempotencia y respuesta de éxito esperada. Manténgalo interno o resúmalo en una oración cuando un skill que lo invoca defina un flujo de tutorial autorizado; muestre el plan completo cuando el usuario lo solicite o antes de otras mutaciones.
7. Ejecute una sonda de autenticación segura de solo lectura antes de la primera mutación cuando exista un ámbito de lectura aplicable.
8. Serialice el cuerpo de la solicitud exactamente una vez y calcule el hash de los bytes exactos que se enviarán.
9. Construya la cadena canónica con el destino exacto de la solicitud, incluida la cadena de consulta sin procesar.
10. Solicite confirmación inmediatamente antes de una solicitud que cambie el estado, a menos que un skill que lo invoca haya capturado previamente una autorización permanente explícita y estrictamente delimitada. En particular, $brosettlement-onboarding puede autorizar exactamente una cuenta de ledger de staging/testnet y una wallet de staging/testnet vinculada como parte del tutorial solicitado. Esta excepción nunca cubre la inicialización de MPC, retiros, firmas, actividad en producción/mainnet, acciones destructivas o recursos adicionales.
11. Firme y envíe la solicitud confirmada una vez con todos los encabezados requeridos.
12. Valide el estado HTTP y analice los errores utilizando el esquema de error documentado.
13. Verifique el recurso resultante o el ciclo de vida a través de un punto final de lectura y, cuando sea relevante, eventos WebSocket.
14. Para resultados inciertos, lea el recurso o el estado antes de reintentar. Reutilice la misma clave de idempotencia solo para la solicitud lógica idéntica.
15. Reporte la operación, el entorno de destino, el estado, la respuesta de la API saneada, los identificadores y el resultado de la verificación sin exponer secretos. Después de una creación, lea el recurso de vuelta y declare el éxito explícitamente solo cuando la verificación sea exitosa.

Invariantes de firma canónica

Para REST, use exactamente seis campos separados por nueva línea: METHOD, EXACT_REQUEST_TARGET, BODY_HASH, TIMESTAMP, NONCE y API_KEY_ID.

• Conserve la cadena de consulta sin procesar exactamente como se envía; nunca elimine todo después de ?.
• Incluya API_KEY_ID como la sexta línea; nunca use el formato obsoleto de cinco líneas.
• Firme los mismos bytes del cuerpo serializado que el cliente HTTP envía.
• Mantenga X-Idempotency-Key fuera de la cadena canónica.
• Nunca reutilice un nonce.
• Trate WS_CONNECT como una canónica WebSocket separada de cuatro líneas; nunca reutilice la lógica de firma REST.

Si el cliente Go empaquetado no se puede utilizar, implemente estos mismos invariantes en el lenguaje del usuario y verifique un vector de prueba de marca de tiempo/nonce fijo localmente antes de cualquier mutación en vivo. No copie un algoritmo de firma de otro skill o documento a menos que coincida con el Swagger actual del entorno seleccionado y los requisitos actuales específicos de la operación en este skill.

Use la CLI empaquetada

Use la CLI Go unificada como la superficie de ejecución predeterminada. En la primera solicitud, o cuando el binario falte, constrúyalo a partir del código fuente empaquetado:

./scripts/build-cli.sh

Al inicio de cada solicitud que active este skill, ejecute exactamente una comprobación de actualización automática antes de cualquier operación de la API de BroSettlement:

./scripts/go/bin/brosettlement update --auto
./scripts/go/bin/brosettlement version

El actualizador acepta únicamente los lanzamientos publicados de GitHub cli-vMAJOR.MINOR.PATCH del repositorio oficial, selecciona el binario del sistema operativo/arquitectura actual, verifica checksums.txt y cualquier resumen de activo SHA-256 de GitHub, verifica la versión reportada por la CLI descargada y reemplaza atómicamente solo el ejecutable actual. Nunca debe extraer, clonar, reescribir o actualizar el contenido del skill.

Si GitHub no está disponible, no existe ningún lanzamiento de CLI publicado todavía, la plataforma no es compatible, el checksum falla o el directorio del ejecutable no es escribible, reporte la actualización omitida brevemente y continúe con la CLI instalada cuando admita el comando requerido. Nunca debilite la verificación de checksum o de fuente para hacer que una actualización tenga éxito.

Mantenga cmd/list-commands, cmd/api-request y cmd/ws-listener solo como puntos de entrada heredados compatibles. No ensamble firmas con comandos de shell ad hoc cuando la CLI unificada esté disponible.

Presente comandos al usuario

Al enseñar o devolver un comando reutilizable en el chat, use la superficie de comando portátil @brosettlement en lugar de exponer la ruta interna del ejecutable del skill. Presente los comandos de esta forma:

# Lista completa de comandos
@brosettlement commands

# Búsqueda por tema
@brosettlement commands wallets
@brosettlement commands "ledger balance" --json

# Solicitud REST firmada
@brosettlement api GET '/api/v1/wallets'

# Estado de MPC
@brosettlement mpc status

# WebSocket
@brosettlement websocket listen --stop-after 30s

Trate @brosettlement como la invocación orientada al usuario manejada por el skill instalado. Al ejecutar realmente la operación, resuélvalo a la CLI verificada empaquetada en ./scripts/go/bin/brosettlement (o la ruta instalada absoluta equivalente). Muestre la ruta nativa solo para solución de problemas directa en el shell, compilaciones, actualizaciones o cuando el agente del usuario no admita la superficie de comando @brosettlement.

Responda preguntas sobre comandos de la API

Use el listador de comandos Go siempre que el usuario pregunte qué está disponible o solicite una operación por tema. Obtiene Swagger en cada ejecución.

./scripts/go/bin/brosettlement commands
./scripts/go/bin/brosettlement commands wallets
./scripts/go/bin/brosettlement commands "ledger balance" --json

Devuelva los métodos HTTP, rutas y resúmenes de Swagger coincidentes. Luego inspeccione la operación seleccionada en el JSON de Swagger antes de generar cargas útiles o código. No responda desde la instantánea de punto final empaquetada cuando el Swagger de staging en vivo sea accesible.

Envíe solicitudes REST firmadas

Prefiera el cliente de solicitudes Go:

export BROSETTLEMENT_API_KEY_ID="<uuid>"
export BROSETTLEMENT_API_PRIVATE_KEY_FILE="/secure/path/private.pem"

./scripts/go/bin/brosettlement api GET '/api/v1/wallets'

./scripts/go/bin/brosettlement api POST '/api/v1/wallets' \
  --body-file /secure/path/create-wallet.json \
  --confirm

El cliente firma el destino exacto y los bytes del cuerpo, agrega los hashes de cuerpo vacío requeridos y las claves de idempotencia para las operaciones actualmente documentadas por Swagger, envía la solicitud e imprime una respuesta estructurada. GET, HEAD y OPTIONS se ejecutan directamente. Cualquier otro método requiere --confirm. Proporciónelo solo después de una autorización explícita: ya sea confirmación inmediata del usuario o autorización permanente limitada definida por el skill que lo invoca. La excepción de incorporación cubre solo una cuenta de ledger de staging/testnet y una wallet de staging/testnet vinculada; no elimina la salvaguarda de la CLI ni autoriza ninguna otra mutación.

Para POST /api/v1/mpc/initialize, siga exactamente el contrato de operación del entorno seleccionado actual. Los contratos verificados de producción y staging actualmente requieren:

• enviar el cuerpo JSON exacto de dos bytes {} con Content-Type: application/json;
• establecer X-Api-Body-Hash y la línea canónica BODY_HASH en 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a;
• nunca enviar un cuerpo de longitud cero ni reformatear la carga útil.

El comando protegido mpc initialize proporciona {} automáticamente. No reintente combinaciones alternativas de cuerpo/hash después de un resultado incierto; verifique primero GET /api/v1/mpc/status y reutilice la misma clave de idempotencia solo para la misma inicialización lógica.

Use los comandos de conveniencia protegidos durante la incorporación:

./scripts/go/bin/brosettlement mpc status
./scripts/go/bin/brosettlement mpc initialize \
  --idempotency-key '<stable-key-for-this-initialization>' \
  --confirm

El generador de encabezados Node.js sin dependencias sigue disponible cuando solo se necesitan encabezados de firma:

Use scripts/sign-request.mjs para producir encabezados de solicitud a partir de un método exacto, destino de solicitud y archivo de cuerpo opcional:

BROSETTLEMENT_API_KEY_ID="<uuid>" \
BROSETTLEMENT_API_PRIVATE_KEY_FILE="/secure/path/private.pem" \
node scripts/sign-request.mjs \
  --method POST \
  --target /api/v1/wallets \
  --body-file /tmp/request.json \
  --idempotency-key "<stable-key-for-this-logical-request>"

Envíe los mismos bytes de --body-file; reformatear JSON después de firmar invalida el hash del cuerpo y la firma. Si una operación documentada requiere idempotencia y se omite --idempotency-key, el generador añade req-<nonce>. Pase una clave estable explícita al preparar una solicitud que pueda reintentarse.

Escuche eventos WebSocket

Use el listener Go:

export BROSETTLEMENT_API_KEY_ID="<uuid>"
export BROSETTLEMENT_API_PRIVATE_KEY_FILE="/secure/path/private.pem"

./scripts/go/bin/brosettlement websocket listen \
  --log-path ./brosettlement_ws_listener.log

Para una prueba de humo limitada:

./scripts/go/bin/brosettlement websocket listen --stop-after 30s

El listener usa la cadena canónica separada WS_CONNECT, se reconecta después de fallos y escribe líneas JSON estructuradas en la salida estándar y un archivo de registro local protegido. Nunca registre la URL de WebSocket firmada porque su consulta contiene material de autenticación.

Reglas de seguridad

• Nunca invente puntos finales, campos, ámbitos, identificadores de red o valores de estado.
• Nunca exponga ni solicite una clave privada cuando una clave pública, ID de clave, firma o diagnóstico redactado sea suficiente.
• Nunca solicite una contraseña, JWT, código TOTP o sesión autenticada de la Consola para gestionar claves API.
• Nunca cree, edite, rote o revoque claves API para el usuario; la gestión de claves API es solo para el usuario.
• Nunca registre cadenas canónicas cuando puedan contener parámetros de consulta sensibles.
• Trate producción y staging como entornos API distintos, y testnet y mainnet como objetivos de blockchain distintos. Producción es el entorno API predeterminado, pero la actividad de mainnet aún requiere autorización explícita.
• Trate las acciones de creación, retiro, inicialización de MPC y firma como cambios de estado. Confirme el recurso y el entorno previstos antes de ejecutarlos.
• No reintente una mutación con una nueva clave de idempotencia después de un resultado desconocido hasta que se haya verificado el resultado existente.
• No declare éxito solo a partir de una solicitud HTTP; verifique el recurso resultante o el estado del ciclo de vida terminal.

WebSocket

Los formatos de firma REST y WebSocket difieren. Use el formato canónico WebSocket en la referencia de la API y requiera websockets:read. Consuma eventos de forma idempotente por ID de evento, tolere duplicados y reconexiones, persista cursores cuando sea compatible y concilie eventos con recursos REST y registros de ledger.