# API_REFERENCE.md — Referencia Completa de Endpoints (4GatosCoin)

Este documento describe todos los endpoints disponibles en el ecosistema 4GatosCoin, incluyendo DevWeb3, órganos internos, estadísticas, puntos, semillas, logs y estado global.

Todos los endpoints siguen el patrón:

```
/app/api/<endpoint>/route.ts
```

Las respuestas son siempre JSON.

---

# 1. Autenticación

## `POST /api/auth`
Autenticación basada en wallet y firma.

### Body
```json
{
  "wallet": "0x123...",
  "signature": "..."
}
```

### Respuesta
```json
{
  "authenticated": true,
  "wallet": "0x123..."
}
```

---

# 2. Gestos

## `POST /api/gesture`
Registra un gesto en el organismo.

### Body
```json
{
  "wallet": "0x123...",
  "gesture": "pulso_vocal"
}
```

### Respuesta
```json
{
  "success": true,
  "gestureId": "...",
  "pointsAdded": 3
}
```

---

## `GET /api/getGestureCounts`
Devuelve el conteo total de gestos por tipo.

### Respuesta
```json
{
  "pulso_vocal": 120,
  "pause": 45,
  "walletConnect": 88
}
```

---

# 3. Organismo Global

## `GET /api/organismo-global`
Devuelve el estado completo del organismo.

### Respuesta
```json
{
  "energia": 1200,
  "territorio": 4,
  "ciclos": 12,
  "heartbeat": 88,
  "flags": {
    "apagado": false
  }
}
```

---

## `POST /api/organismo-global`
Actualiza el estado global.

### Body
```json
{
  "energia": 1300
}
```

### Respuesta
```json
{
  "updated": true
}
```

---

# 4. Puntos

## `GET /api/points`
Devuelve puntos por wallet.

### Query
```
/api/points?wallet=0x123...
```

### Respuesta
```json
{
  "wallet": "0x123...",
  "points": 42
}
```

---

# 5. Semillas

## `GET /api/seeds`
Devuelve semillas generadas y su distribución.

### Respuesta
```json
{
  "total": 120,
  "byWallet": {
    "0x123...": 4,
    "0xabc...": 2
  }
}
```

---

# 6. Logs

## `GET /api/logs`
Devuelve logs del organismo.

### Query opcional
```
/api/logs?type=gesture
```

### Respuesta
```json
[
  {
    "type": "gesture",
    "wallet": "0x123...",
    "timestamp": 1700000000
  }
]
```

---

# 7. Rituales

## `GET /api/ritual`
Devuelve estado ritual actual.

### Respuesta
```json
{
  "ritual": "elgritoquecrea",
  "active": true,
  "participants": 88
}
```

---

# 8. Ritugato

## `GET /api/ritugato`
Devuelve estado del órgano Ritugato.

### Respuesta
```json
{
  "eco": 12,
  "silencio": 4,
  "reflejo": 9
}
```

---

# 9. Estadísticas de Cláusulas

## `GET /api/clause-stats`
Devuelve estadísticas del ritual *El Grito Que Crea*.

### Respuesta
```json
{
  "totalGestures": 88,
  "lastGesture": "pulso_vocal"
}
```

---

# 10. Milestones

## `GET /api/milestones`
Devuelve hitos automáticos del usuario.

### Query
```
/api/milestones?wallet=0x123...
```

### Respuesta
```json
{
  "wallet": "0x123...",
  "milestones": [
    "primer_gesto",
    "primer_eco",
    "primer_ciclo"
  ]
}
```

---

# 11. Perfil

## `GET /api/profile`
Devuelve perfil ritual del usuario.

### Query
```
/api/profile?wallet=0x123...
```

### Respuesta
```json
{
  "wallet": "0x123...",
  "points": 42,
  "seeds": 4,
  "gestures": 12
}
```

---

# 12. NFTs

## `GET /api/nfts`
Devuelve NFTs rituales asociados a una wallet.

### Respuesta
```json
{
  "wallet": "0x123...",
  "nfts": [
    {
      "id": "ritual-001",
      "type": "eco"
    }
  ]
}
```

---

# 13. Posts (Narrativa)

## `GET /api/posts`
Devuelve posts narrativos del organismo.

### Respuesta
```json
[
  {
    "id": "post-001",
    "title": "El Eco Inicial",
    "body": "..."
  }
]
```

---

# 14. Auranet

## `POST /api/auranet/register`
Registra un usuario en Auranet.

### Body
```json
{
  "wallet": "0x123...",
  "username": "gatito"
}
```

---

# 15. Territorio

## `GET /api/territorio`
Devuelve estado territorial del organismo.

### Respuesta
```json
{
  "zonas": 4,
  "dominancia": {
    "norte": 12,
    "sur": 8
  }
}
```

---

# 16. Heartbeat

## `GET /api/heartbeat`
Devuelve el latido global.

### Respuesta
```json
{
  "heartbeat": 88,
  "lastUpdate": 1700000000
}
```

---

# 17. Sandbox

## `POST /api/sandbox`
Endpoint para pruebas internas.

### Body
```json
{
  "action": "test",
  "payload": {}
}
```

---

# 18. Resumen de Endpoints

```
/api/auth
/api/gesture
/api/getGestureCounts
/api/organismo-global
/api/points
/api/seeds
/api/logs
/api/ritual
/api/ritugato
/api/clause-stats
/api/milestones
/api/profile
/api/nfts
/api/posts
/api/auranet
/api/territorio
/api/heartbeat
/api/sandbox
```

---

# 19. Notas Finales

- Todos los endpoints deben usarse desde DevWeb3 o servicios internos.  
- Ninguno está diseñado para consumo público.  
- La seguridad y validación son obligatorias.  
- El organismo depende de la consistencia de estas rutas.