# Developer API Endpoints

### **Overview**

The HashCloud **Developer API** provides a secure and verifiable interface for miners to communicate with the network backend.\
Through this API, mining clients can fetch computational challenges, submit proofs, query historical performance, and retrieve pending rewards.\
Each interaction is cryptographically validated to ensure data authenticity, miner identity verification, and network-wide synchronization.

The API serves as the foundation for decentralized compute interaction, enabling miners, pool operators, and analytic dashboards to integrate directly with the **Proof-of-Compute** protocol in real time.

### **Core Endpoints**

| **Method** | **Path**        | **Description**                                                                                                                                              |
| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **GET**    | `/challenge`    | Fetches a new deterministic matrix computation challenge for the miner. Each challenge includes matrix parameters, seed data, and time constraints.          |
| **POST**   | `/submit-proof` | Submits a miner’s computed proof result for backend verification. The proof packet must include hashes, timestamps, and cryptographic signatures.            |
| **GET**    | `/performance`  | Retrieves a miner’s historical performance data, including verified computation scores and task efficiency metrics. Useful for benchmarking and diagnostics. |
| **GET**    | `/rewards`      | Queries pending daily rewards for the authenticated miner. Returns token distribution data for the most recent emission cycle.                               |

{% hint style="info" %}

* All endpoints require wallet authentication.
* Responses are cryptographically hashed for integrity.
  {% endhint %}

### **Authentication and Security**

To maintain trustless integrity, all API requests require cryptographic authentication tied to the miner’s registered wallet.\
This ensures that only authorized participants can submit proofs or claim rewards.

#### **Authentication Model**

* **Wallet-Based Authorization:** Each API call must include a valid wallet signature for identity verification.
* **Nonce Validation:** Every request includes a unique nonce to prevent replay attacks.
* **Encrypted Transport:** All communication between clients and the backend uses **HTTPS (TLS 1.3)** to safeguard sensitive data.
* **Signature Integrity:** Proofs and payloads are hashed and signed before transmission to ensure immutability.

By integrating cryptographic standards directly into the protocol layer, the HashCloud API guarantees that all interactions remain verifiable, secure, and tamper-resistant.

### **Response Format**

All API responses are structured in standardized JSON format, ensuring easy integration with mining software, monitoring tools, and third-party dashboards.

#### **Example Response — `/challenge`**

```json
{
  "challenge_id": "0x8a5b...",
  "matrix_size": 512,
  "seed": "0x7f91...",
  "issued_at": "2025-10-30T00:00:00Z",
  "expires_in": 600
}
```

#### **Example Response — `/submit-proof`**

```json
{
  "status": "verified",
  "compute_score": 4821,
  "reward_estimate": 12.45,
  "timestamp": "2025-10-30T00:10:00Z"
}
```

These outputs allow miners to monitor compute cycles, analyze performance, and confirm that their results were successfully verified.

### **Error Handling**

| **Error Code** | **Description**                                    | **Recommended Action**                     |
| -------------- | -------------------------------------------------- | ------------------------------------------ |
| **401**        | Unauthorized request or invalid wallet signature   | Reauthenticate wallet and retry submission |
| **403**        | Proof submission rejected due to expired challenge | Fetch a new challenge and recompute proof  |
| **429**        | Too many requests from miner                       | Implement rate-limiting or delay retries   |
| **500**        | Internal backend error                             | Wait a few minutes and resubmit proof      |

All responses include a descriptive error message to guide miners in resolving API-related issues quickly.

### **Developer Notes**

* All endpoints require **wallet authentication** prior to submission or query.
* Responses are **cryptographically hashed** for verification and logged by the backend for auditing.
* Rate limits may apply per node to ensure network stability.
* API documentation will evolve as new endpoints are added for governance, staking, and compute leasing.

Developers integrating with HashCloud should regularly monitor the official documentation repository for version updates, schema changes, and security advisories.

### **Purpose and Design Intent**

The HashCloud API was designed with three guiding principles:

1. **Transparency:** Every response is verifiable and traceable through blockchain-integrated proofs.
2. **Security:** End-to-end encryption and signature verification ensure only legitimate miners interact with the network.
3. **Interoperability:** The use of open standards and JSON-based schemas enables easy adoption by third-party developers, monitoring dashboards, and mining pools.

Through these standards, the API becomes a **trust anchor** for the entire HashCloud compute economy bridging the gap between decentralized hardware and verifiable digital reward systems.