> For the complete documentation index, see [llms.txt](https://docs.nearby.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nearby.finance/developers/nearby-protocol-api-reference.md).

# Nearby Protocol API Reference

### Overview

Nearby Protocol exposes three primary API surfaces:

* **Proof of Location API**
* **Nearby Mesh API**
* **OfflinePay API**

All APIs support:

* JSON-based payloads
* Cryptographic verification objects
* Device attestation fields where applicable

Base URL:

```
https://api.nearby.protocol
```

***

## 1. Proof of Location API

### 1.1 Create Location Proof Request

#### `POST /v1/proofs/request`

Creates a request for generating a zero-knowledge location proof on the user device.

#### Request Body

```
{  "type": "location_proof",  "constraint": {    "region": "string",    "radius_meters": "number",    "geo_polygon": "optional[string]"  },  "metadata": {    "purpose": "event_access | reward | verification | custom",    "expires_at": "unix_timestamp"  }}
```

#### Response

```
{  "request_id": "string",  "status": "pending",  "challenge": "zk_challenge_hash"}
```

***

### 1.2 Submit Location Proof

#### `POST /v1/proofs/submit`

#### Request Body

```
{  "request_id": "string",  "proof": "zk_proof_blob",  "public_inputs": {    "region": "string",    "timestamp": "number"  },  "device_attestation": "string"}
```

#### Response

```
{  "valid": true,  "proof_id": "string",  "verified_at": "timestamp"}
```

***

### 1.3 Verify Proof

#### `POST /v1/proofs/verify`

#### Request Body

```
{  "proof": "zk_proof_blob",  "public_inputs": {}}
```

#### Response

```
{  "valid": true,  "confidence_score": 0.98}
```

***

### 1.4 Get Proof Status

#### `GET /v1/proofs/{proof_id}`

#### Response

```
{  "proof_id": "string",  "status": "verified | pending | rejected",  "region": "string",  "timestamp": "number"}
```

***

## 2. Nearby Mesh API

### 2.1 Register Device

#### `POST /v1/mesh/register`

```
{  "device_id": "string",  "public_key": "string",  "capabilities": {    "bluetooth": true,    "wifi_direct": true,    "nfc": true  }}
```

#### Response

```
{  "mesh_node_id": "string",  "status": "registered"}
```

***

### 2.2 Join Mesh Network

#### `POST /v1/mesh/join`

```
{  "mesh_node_id": "string",  "context": "event_id | location_id | custom_group",  "proximity_required": true,  "proof_of_location_id": "optional"}
```

#### Response

```
{  "joined": true,  "context": "string",  "neighbors_detected": 12}
```

***

### 2.3 Send Mesh Message

#### `POST /v1/mesh/message/send`

```
{  "from": "node_id",  "context": "string",  "message": {    "type": "chat | event | alert",    "content": "string"  },  "encryption": "end_to_end | local_only"}
```

#### Response

```
{  "message_id": "string",  "status": "broadcasting"}
```

***

### 2.4 Receive Messages (Streaming)

#### `WS /v1/mesh/message/stream`

```
{  "event": "message_received",  "data": {    "from": "node_id",    "content": "string",    "timestamp": "number"  }}
```

***

### 2.5 Discover Nearby Nodes

#### `GET /v1/mesh/discover`

#### Response

```
{  "nodes": [    {      "node_id": "string",      "distance_estimate": "number",      "signal_strength": "number"    }  ]}
```

***

## 3. OfflinePay API

### 3.1 Create Offline Payment Note

#### `POST /v1/offlinepay/create`

```
{  "sender": "public_key",  "recipient": "public_key",  "amount": 10,  "token": "USDC | USDT"}
```

#### Response

```
{  "payment_note": {    "note_id": "string",    "amount": 10,    "signature": "string",    "issuer": "string"  }}
```

***

### 3.2 Send Offline Payment

#### `POST /v1/offlinepay/send`

Supports offline transport (QR / BLE / NFC / Mesh).

```
{  "payment_note": "encrypted_blob",  "transport": "qr | bluetooth | nfc | mesh"}
```

#### Response

```
{  "status": "delivered | pending_transfer",  "local_validation": true}
```

***

### 3.3 Validate Offline Payment

#### `POST /v1/offlinepay/validate`

```
{  "payment_note": "string"}
```

#### Response

```
{  "valid": true,  "reason": "signature_verified | invalid_note | double_spend_risk"}
```

***

### 3.4 Receive Payment

#### `WS /v1/offlinepay/receive`

```
{  "event": "payment_received",  "data": {    "note_id": "string",    "amount": 10,    "token": "USDC"  }}
```

***

### 3.5 Sync & Reconciliation

#### `POST /v1/offlinepay/sync`

Triggers global reconciliation when connectivity is restored.

```
{  "device_id": "string",  "transaction_history": "encrypted_blob"}
```

#### Response

```
{  "status": "processing",  "conflicts_detected": false,  "finalized": false}
```

***

### 3.6 Witness Attestation

#### `POST /v1/offlinepay/witness`

```
{  "transaction_id": "string",  "witness_signature": "string",  "context": "mesh_event_id"}
```

#### Response

```
{  "accepted": true,  "reward_eligible": true}
```

***

## Common Schemas

### Device Attestation Object

```
{  "device_id": "string",  "attestation_signature": "string",  "tee_status": "verified | unverified",  "timestamp": "number"}
```

***

### zk Proof Object

```
{  "proof": "zkSNARK_blob",  "public_inputs": {},  "verification_key": "string"}
```

***

### Payment Note Object

```
{  "note_id": "string",  "amount": "number",  "token": "USDC | USDT",  "owner_public_key": "string",  "signature": "string"}
```

***

## API Design Principles

Nearby APIs follow five core principles:

#### 1. Offline-first compatibility

All critical flows work without internet connectivity.

#### 2. Cryptographic verification

All state transitions are verifiable using zk proofs or signatures.

#### 3. Minimal trust assumptions

No reliance on centralized validation services.

#### 4. Eventual consistency

Offline state is reconciled globally when connectivity returns.

#### 5. Layer composability

Proof of Location, Mesh and OfflinePay can be used independently or together.

***

## Developer Summary

Nearby Protocol APIs enable developers to build applications that:

* Verify real-world presence without exposing location data
* Enable local communication without internet dependency
* Support financial transactions without real-time connectivity

All within a single unified infrastructure stack.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nearby.finance/developers/nearby-protocol-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.