> 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/developer-documentation.md). # Developer Documentation ### Overview Nearby Protocol provides three core developer interfaces: * **Proof of Location API** - verify physical presence using zk proofs * **Nearby Mesh SDK** - build decentralized, local-first communication apps * **OfflinePay SDK** - enable offline stablecoin transactions between devices All components are designed to work independently or as a unified stack. *** ## Proof of Location API ### Overview The Proof of Location API allows applications to verify that a user is physically present within a defined geographic area without exposing raw location data. Developers can integrate location verification into: * Access control systems * Event participation apps * Reward systems * Location-based services * Real-world asset applications *** ### Core Concept Instead of receiving GPS coordinates, applications receive: > A cryptographic proof that a location condition is satisfied. Example: * “User is within Berlin” * “User is inside Event Zone A” * “User is within EU region boundary” *** ### Integration Flow #### 1. Request Proof Your application requests a proof from the user’s device: ``` POST /proof/request ``` Example payload: ``` { "type": "location_proof", "constraint": { "region": "Berlin", "radius": 5000 }} ``` *** #### 2. User Device Generates Proof On the user device: * Location signals are collected locally * Integrity checks are executed inside TEE * zkSNARK proof is generated * Device attestation is attached *** #### 3. Proof Returned Your backend receives: ``` { "proof": "zk_proof_hash", "public_inputs": { "region": "Berlin", "timestamp": 1730000000 }, "attestation": "device_signature"} ``` *** #### 4. Verification Verify proof: ``` POST /proof/verify ``` Response: ``` { "valid": true} ``` *** ### Key Properties * No raw GPS data exposed * Verifiable on-chain or off-chain * Device-backed authenticity * zk-based privacy guarantees *** ### Use Cases * Geo-gated access control * Proof-of-attendance systems * Location-based rewards * Regulatory compliance checks * Real-world asset verification *** ## Nearby Mesh SDK ### Overview Nearby Mesh enables developers to build applications that communicate through local, peer-to-peer networks without requiring internet connectivity. It is designed for: * Event apps * Emergency communication systems * Local social networks * Offline-first messaging apps * Geo-based communities *** ### Architecture Model Nearby Mesh is built on: * Peer discovery layer * Message relay system * Local context grouping (events/zones) * Optional Proof of Location gating *** ### Installation ``` npm install @nearby/mesh-sdk ``` *** ### Initialize Mesh Node ``` import { NearbyMesh } from "@nearby/mesh-sdk";const mesh = new NearbyMesh({ appId: "your-app-id", mode: "event"});await mesh.init(); ``` *** ### Join Local Network ``` await mesh.join({ context: "concert-123", proximity: true}); ``` *** ### Send Message ``` mesh.send({ type: "chat", content: "Hello nearby users!"}); ``` *** ### Receive Messages ``` mesh.onMessage((msg) => { console.log("New local message:", msg);}); ``` *** ### Network Behavior * Devices automatically discover nearby peers * Messages are relayed across devices * No central server required * Network forms dynamically based on physical proximity *** ### Optional Features #### Proof of Location Gating Restrict access: ``` if (proof.valid && proof.region === "event-zone") { mesh.join("vip-channel");} ``` *** ### Use Cases * Event communication apps * Festival coordination tools * Emergency alert systems * Local community apps * Offline social networks *** ## OfflinePay SDK ### Overview OfflinePay enables developers to integrate offline stablecoin payments into applications and devices. It supports: * USDC * USDT Payments can be made without internet connectivity and later settled on-chain. *** ### Core Concept OfflinePay uses **cryptographically signed payment notes** instead of direct blockchain transactions during offline mode. *** ### Installation ``` npm install @nearby/offlinepay-sdk ``` *** ### Initialize Wallet ``` import { OfflinePay } from "@nearby/offlinepay-sdk";const wallet = new OfflinePay({ network: "base"});await wallet.init(); ``` *** ### Create Offline Payment ``` const tx = await wallet.createPayment({ to: "recipient_public_key", amount: 10, token: "USDC"}); ``` *** ### Transfer Offline (No Internet Required) Supported channels: * QR transfer * Bluetooth * NFC * Mesh relay (via Nearby Mesh) ``` await wallet.sendOffline(tx); ``` *** ### Receive Payment ``` wallet.onReceive((paymentNote) => { console.log("Received offline payment:", paymentNote);}); ``` *** ### Local Validation Rules Each device validates: * Signature authenticity * Value conservation * Note integrity * Ownership proof *** ### Reconciliation (Online Phase) When internet is restored: ``` wallet.sync() ``` This: * Submits offline transaction history * Detects conflicts (double-spend cases) * Finalizes settlement on-chain * Updates balances *** ### Witness Integration Devices can optionally act as witnesses: ``` wallet.onTransaction((tx) => { wallet.signWitness(tx);}); ``` Witness rewards are distributed in $NEARBY. *** ### Use Cases * Offline commerce * Festival payments * Emergency financial systems * Peer-to-peer trading in low connectivity areas * Cross-border cashless exchange without internet *** ## Developer Summary Nearby Protocol provides three independent but composable SDK layers: | Layer | Purpose | | ----------------- | --------------------------------------- | | Proof of Location | Verify physical presence with zk proofs | | Nearby Mesh | Enable local peer-to-peer communication | | OfflinePay | Enable offline stablecoin transfers | *** ## Final Developer Vision Nearby is designed as a **physical-world development stack**, where applications can operate across: * Fully connected environments * Partially connected environments * Fully offline environments Developers do not need to choose between online and offline systems. They build once and the protocol adapts to the environment. --- # 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/developer-documentation.md?ask= ``` 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.