API OTC - Documentación

Resumen

Esta API permite subir archivos (PDF, imágenes, audio, video), generar un hash SHA-256, almacenar el archivo en IPFS y registrar el hash en Polygon.

Límites y costes por acción

Las acciones que tengan coste adicional pueden limitarse por tipo de cliente y por cliente. El consumo se reinicia según el periodo configurado (por defecto mensual) sin perder el histórico, que queda registrado en action_usage.

polygon_write: registra hashes en Polygon al subir un archivo.
polygon_read: consultas a la red Polygon (si se habilitan).
ipfs_retrieve: accesos de recuperación de contenido distribuido.

Si un cliente llega al límite de una acción, no podrá ejecutar esa acción hasta el siguiente periodo. Las acciones sin coste (o sin límites configurados) se pueden usar sin restricción.

Autenticación

Para los endpoints de archivos, incluye el header X-Client-Api-Key del cliente.

X-Client-Api-Key: tu-api-key-de-cliente

Para gestión de contratos, usa el header X-API-Key.

X-API-Key: tu-api-key-larga

Endpoint de subida

POST /v1/files

Content-Type: multipart/form-data

Este endpoint es idempotente para el mismo cliente: si subes el mismo archivo (mismo SHA-256), devuelve el registro existente y no genera una nueva transacción.

curl -X POST https://block.addaw.org/v1/files \
  -H "X-Client-Api-Key: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" \
  -F "file=@/ruta/archivo.pdf"

Respuesta:

{
  "sha256": "...",
  "ipfs_cid": "...",
  "polygon_tx_hash": "...",
  "mime_type": "application/pdf",
  "client_id": 1
}

Si el archivo ya existe para ese cliente, la respuesta será 200 con los mismos campos.

Consulta de material

GET /v1/files/{sha256}

curl https://block.addaw.org/v1/files/<sha256> \
  -H "X-Client-Api-Key: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

Respuesta:

{
  "sha256": "...",
  "ipfs_cid": "...",
  "ipfs_url": "https://ipfs.io/ipfs/...",
  "polygon_tx_hash": "...",
  "mime_type": "application/pdf",
  "original_name": "archivo.pdf",
  "size_bytes": 12345,
  "created_at": "2025-01-01 10:00:00"
}

Activación de contratos

POST /v1/contracts/{address}/activate

Activa la dirección del contrato para la red indicada y desactiva cualquier contrato activo previo.

curl -X POST https://block.addaw.org/v1/contracts/0xTuContrato/activate \
  -H "X-API-Key: tu-api-key-larga" \
  -H "Content-Type: application/json" \
  -d '{"network":"polygon","tx_hash":"0xhash","deployed_at":"2025-01-01 12:00:00"}'

Respuesta:

{
  "address": "0xTuContrato",
  "network": "polygon",
  "tx_hash": "0xhash",
  "deployed_at": "2025-01-01 12:00:00",
  "is_active": true
}

POST /v1/contracts/{address}/deactivate

Desactiva el contrato indicado para la red.

curl -X POST https://block.addaw.org/v1/contracts/0xTuContrato/deactivate \
  -H "X-API-Key: tu-api-key-larga" \
  -H "Content-Type: application/json" \
  -d '{"network":"polygon"}'

Base de datos

Ejecuta el script database.sql para crear la estructura de clientes, uso y registros.

Incluye un cliente por defecto llamado usuarioDePruebas con límites por acción.

DB_DSN=mysql:host=127.0.0.1;dbname=api_otc;charset=utf8mb4
DB_USER=usuario
DB_PASS=clave

Inserciones incluidas en database.sql:

INSERT INTO client_types (id, name, reset_period)
VALUES (1, 'basico', 'monthly');

INSERT INTO client_type_action_limits (client_type_id, action_key, limit_per_period, cost_per_action)
VALUES
  (1, 'polygon_write', 100, 0.05000000),
  (1, 'polygon_read', 200, 0.02000000),
  (1, 'ipfs_retrieve', 500, 0.00000000);

INSERT INTO clients (name, api_key, client_type_id, is_active)
VALUES ('usuarioDePruebas', '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef', 1, 1);

Configuración para clientes

Esta documentación pública solo describe el uso de la API desde clientes. El detalle de variables de entorno y despliegue está en SETUP_POLYGON_IPFS.txt.

Necesitarás una clave de cliente válida para usar los endpoints de archivos.