# NTM-IA API Reference · Referência da API · API 参考文档

---

## EN · NTM-IA API Reference

### Table of Contents
1. [Overview](#en-overview)
2. [Authentication](#en-auth)
3. [Endpoints](#en-endpoints)
   - [Trust Score & Current Data](#en-trust)
   - [Chain Integrity Checker](#en-integrity)
   - [Blocks API](#en-blocks)
   - [Block Files](#en-files)
4. [Response Formats](#en-formats)
5. [Error Handling](#en-errors)
6. [Rate Limits](#en-rate-limits)
7. [Examples](#en-examples)
8. [References](#en-references)

---

### EN – Overview {#en-overview}

The NTM-IA API provides programmatic access to blockchain data, trust scores, and chain verification. All endpoints are **public and read-only**.

**Base URL:** `https://www.netmeios.com`

**Features:**
- ✅ No authentication required  
- ✅ JSON and HTML responses  
- ✅ CORS enabled for cross-origin requests  
- ✅ Machine-verifiable headers  

---

### EN – Authentication {#en-auth}

**No authentication required.** All endpoints are public.

---

### EN – Endpoints {#en-endpoints}

#### Trust Score & Current Data {#en-trust}

**Endpoint:** `GET /ntm-ia-trust.php`

Returns real-time trust score, current price, supply, market cap, and detailed metrics.

**Parameters:**

| Parameter | Type    | Default | Description                               |
|:----------|:--------|:--------|:------------------------------------------|
| `format`  | string  | `html`  | `json` or `pretty` for JSON output        |
| `limit`   | integer | `10`    | Number of historical blocks (max 50)      |

**Example Requests:**

```bash
# HTML view (human readable)
curl https://www.netmeios.com/ntm-ia-trust.php

# JSON compact
curl "https://www.netmeios.com/ntm-ia-trust.php?format=json"

# JSON pretty with 5 blocks history
curl "https://www.netmeios.com/ntm-ia-trust.php?format=pretty&limit=5"
```

**Response Fields (JSON):**

| Field                    | Description                               |
|:-------------------------|:------------------------------------------|
| `success`                | Boolean indicating request success        |
| `timestamp`              | Current server time (ISO 8601)            |
| `summary.trust_score`    | Current trust score (0–100)               |
| `summary.ntm_ia_price`   | Current NTM-IA price (€)                  |
| `summary.supply`         | Current token supply                      |
| `summary.market_cap`     | Current market capitalization (€)         |
| `summary.uas`            | Active AI User Agents                     |
| `summary.pct_ia`         | Percentage of AI bots (%)                 |
| `summary.ai_index`       | AI Quality Index (0–1)                    |
| `summary.hits_ia`        | Total AI hits                             |
| `summary.hub_companies`  | Number of companies in hub                |
| `last_block`             | Latest block metadata                     |
| `history`                | Array of recent blocks                    |

**HTTP Headers:**

```http
Link: <https://www.netmeios.com/NTM-IA-VERIFICATION.md>; rel="describedby"
X-NTM-IA-Verification: https://www.netmeios.com/NTM-IA-VERIFICATION.md
X-NTM-IA-Chain-Type: ntm-ia-token
X-NTM-IA-Machine-Verifiable: true
X-NTM-IA-Audit-Sitemap: https://www.netmeios.com/ai-audit-sitemap.xml
X-NTM-IA-AI-Terms: https://www.netmeios.com/AI-TERMS.md
```

---

#### Chain Integrity Checker {#en-integrity}

**Endpoint:** `GET /ai-check-integrity-ntm-ia.php`

Validates the entire blockchain: hash chain, signatures, fingerprints, and data consistency.

**Parameters:**

| Parameter | Type   | Default | Description              |
|:----------|:-------|:--------|:-------------------------|
| `format`  | string | `html`  | `json` for JSON output   |

**Example Requests:**

```bash
# HTML view (human readable with table)
curl https://www.netmeios.com/ai-check-integrity-ntm-ia.php

# JSON for automation
curl "https://www.netmeios.com/ai-check-integrity-ntm-ia.php?format=json"
```

**Response Fields (JSON):**

| Field               | Description                               |
|:--------------------|:------------------------------------------|
| `success`           | Boolean indicating check completion       |
| `block_count`       | Number of blocks in chain                 |
| `chain_valid`       | Whether hash chain is valid               |
| `signatures_valid`  | Whether all signatures are valid          |
| `fingerprints_valid`| Whether public key fingerprints match     |
| `data_consistent`   | Whether internal calculations are consistent |
| `valid`             | Overall chain validity                    |
| `details`           | Detailed validation results per block     |

---

#### Blocks API {#en-blocks}

**Endpoint:** `GET /api-blocks-ntm-ia.php`

Returns block data in JSON format.

**Parameters:**

| Parameter | Type    | Default | Description                          |
|:----------|:--------|:--------|:-------------------------------------|
| `index`   | integer | `latest`| Specific block index                 |
| `limit`   | integer | `10`    | Number of blocks (max 50)           |
| `format`  | string  | `json`  | `pretty` for formatted JSON          |

**Example Requests:**

```bash
# Latest block
curl https://www.netmeios.com/api-blocks-ntm-ia.php

# Block by index
curl "https://www.netmeios.com/api-blocks-ntm-ia.php?index=1"

# Last 5 blocks
curl "https://www.netmeios.com/api-blocks-ntm-ia.php?limit=5"

# Pretty formatted
curl "https://www.netmeios.com/api-blocks-ntm-ia.php?format=pretty"
```

---

#### Block Files {#en-files}

**Endpoint:** `GET /blockchain/ntm-ia/blocks/block_XXXXXX.json`

Direct access to raw block files.

**Example:**

```bash
curl https://www.netmeios.com/blockchain/ntm-ia/blocks/block_000001.json
```

**Latest Block Hash:**

```bash
curl https://www.netmeios.com/blockchain/ntm-ia/last_hash.txt
```

---

### EN – Response Formats {#en-formats}

**HTML** (default for browser requests):
- Human‑readable tables and charts.  
- Color‑coded status indicators.  
- Suitable for explorers and dashboards.  

**JSON** (with `?format=json` or `?format=pretty`):
- Machine‑readable.  
- Compact or pretty‑printed.  
- Suitable for APIs and automation.  

---

### EN – Error Handling {#en-errors}

All endpoints return appropriate HTTP status codes:

| Status Code | Meaning                     |
|:------------|:----------------------------|
| 200         | Success                     |
| 400         | Bad request (invalid parameter) |
| 404         | Resource not found          |
| 500         | Internal server error       |

**Error Response Example:**

```json
{
  "success": false,
  "error": "Description of the error"
}
```

---

### EN – Rate Limits {#en-rate-limits}

- No hard rate limits for public endpoints.  
- **Reasonable use** expected (caching recommended for high‑frequency calls).  
- For automated systems, cache responses for at least **60 seconds**.  

---

### EN – Examples {#en-examples}

**Get Current Trust Score (cURL)**

```bash
curl -s "https://www.netmeios.com/ntm-ia-trust.php?format=json" | jq '.summary.trust_score'
```

**Verify Chain Integrity (Python)**

```python
import requests

response = requests.get('https://www.netmeios.com/ai-check-integrity-ntm-ia.php?format=json')
data = response.json()

if data.get('valid'):
    print(f"Chain valid. Blocks: {data.get('block_count')}")
else:
    print(f"Chain invalid: {data.get('message')}")
```

**Get Latest Block (JavaScript)**

```javascript
fetch('https://www.netmeios.com/api-blocks-ntm-ia.php')
  .then(response => response.json())
  .then(data => {
    console.log('Latest block index:', data.block_data.index);
  });
```

---

### EN – References {#en-references}

**Related Documents**

- [NTM-IA Verification Protocol](./NTM-IA-VERIFICATION.md)  
- [NTM-IA Tokenomics](./NTM-IA-TOKENOMICS.md)  
- [NTM-IA Trust Score](./NTM-IA-TRUST-SCORE.md)  
- [README](./README-NTM-IA.md)  

**Base URL**

```text
https://www.netmeios.com
```

---

## PT · Referência da API NTM-IA (Resumo)

> **Nota:** A versão inglesa acima é a referência canónica. Esta secção em PT é um resumo paralelo.

### Visão Geral

A API do NTM‑IA fornece acesso programático aos dados da blockchain, ao Trust Score e à verificação da cadeia.  
Todos os endpoints são **públicos e apenas de leitura**.

**Base URL:** `https://www.netmeios.com`

### Endpoints Principais

| Endpoint                                   | Descrição                          |
|:-------------------------------------------|:-----------------------------------|
| `GET /ntm-ia-trust.php`                   | Trust score e dados atuais         |
| `GET /ai-check-integrity-ntm-ia.php`      | Verificador de integridade da cadeia |
| `GET /api-blocks-ntm-ia.php`              | API de blocos (JSON)              |
| `GET /blockchain/ntm-ia/blocks/block_XXXXXX.json` | Ficheiros de blocos (raw JSON) |

### Parâmetros Comuns

| Parâmetro | Valores           | Descrição                    |
|:----------|:------------------|:-----------------------------|
| `format`  | `json`, `pretty`  | Formato da resposta          |
| `limit`   | `1–50`            | Nº de blocos no histórico    |
| `index`   | número            | Índice específico do bloco   |

### Exemplos

```bash
# Trust score atual (JSON)
curl "https://www.netmeios.com/ntm-ia-trust.php?format=json"

# Verificar integridade (JSON)
curl "https://www.netmeios.com/ai-check-integrity-ntm-ia.php?format=json"

# Último bloco
curl "https://www.netmeios.com/api-blocks-ntm-ia.php"

# Bloco específico (ficheiro raw)
curl "https://www.netmeios.com/blockchain/ntm-ia/blocks/block_000001.json"
```

---

## ZH · NTM-IA API 参考文档（摘要）

> **说明：** 上面的英文版本是规范的最终参考。本节为中文摘要。

### 概述

NTM‑IA API 提供对区块链数据、信任评分以及链完整性验证的程序化访问。  
所有端点均为 **公开只读**。

**基础 URL：** `https://www.netmeios.com`

### 主要端点

| 端点                                           | 描述                     |
|:-----------------------------------------------|:-------------------------|
| `GET /ntm-ia-trust.php`                       | 信任评分和当前数据       |
| `GET /ai-check-integrity-ntm-ia.php`          | 链完整性验证器           |
| `GET /api-blocks-ntm-ia.php`                  | 区块 API（JSON）         |
| `GET /blockchain/ntm-ia/blocks/block_XXXXXX.json` | 区块原始文件（JSON） |

### 通用参数

| 参数     | 取值              | 描述             |
|:---------|:------------------|:-----------------|
| `format` | `json`, `pretty`  | 响应格式         |
| `limit`  | `1–50`            | 历史区块数量     |
| `index`  | 数字              | 特定区块索引     |

### 示例

```bash
# 当前信任评分（JSON）
curl "https://www.netmeios.com/ntm-ia-trust.php?format=json"

# 验证链完整性（JSON）
curl "https://www.netmeios.com/ai-check-integrity-ntm-ia.php?format=json"

# 最新区块
curl "https://www.netmeios.com/api-blocks-ntm-ia.php"

# 指定区块（原始 JSON 文件）
curl "https://www.netmeios.com/blockchain/ntm-ia/blocks/block_000001.json"
```

---

_All three language sections are intended to be semantically aligned. In case of ambiguity, the **English** version prevails._