Submit a location claim - Offline Protocol

Enable Proof of Location in the application’s Proof of Location tab in the developer portal. The caller needs an OfflineID user JWT, an owned profile and App ID. Read the location privacy disclosure before submitting.

Use the SDK

@offline-protocol/pol (0.1.2) submits the commitment and completes the operator witness exchange. It works in React, Next.js and React Native. You supply the App ID, an OfflineID user JWT and the coordinates; the SDK does not sign users in.

npm install @offline-protocol/pol@0.1.2

The package ships TypeScript source, so a Next.js app must transpile it. Add it to transpilePackages in next.config:

// next.config.mjs
export default {
  transpilePackages: ['@offline-protocol/pol'],
};

import { ProofOfLocation } from "@offline-protocol/pol";

const pol = ProofOfLocation.init({
  appId: "app_your_application_id",
  getSessionToken: () => token, // OfflineID JWT after sign-in
});

const proof = await pol.location.verify({ claim: { lat: 51.5074, lon: -0.1278 } });
// proof.attestation, proof.transaction, proof.geohash

Use pol.location.commit({ claim }) when you need only the onchain commitment, without a witness attestation. A ProofOfLocationProvider and useProofOfLocation hook are available for React, and @offline-protocol/pol/wasm provides an optional WASM client for Next.js, covered by the same transpilePackages entry. Validate the returned attestation as described below before relying on it.

Submit with the raw API

POST https://api.offlineprotocol.com/api/v1/profiles/{username}/location-commitment
Authorization: Bearer <user-jwt>
X-App-Id: app_your_application_id
Content-Type: application/json

{"latitude": 51.5074, "longitude": -0.1278}

The response is { "message": "...", "data": { ... } }, with operators, id, transaction, commitment and geoHash inside data. A 200 confirms task submission, not witness acceptance. id is the random task ID. See task identifiers for its format and how to match it to an attestation.

Witness exchange

This describes the operator’s raw protocol, which @offline-protocol/pol implements for you. The older identity SDK hooks do not. The operator must have observed and cached the submitted onchain task before handling the exchange.

Connect to a provisioned operator’s WebSocket. Returned URLs can use https://; map that scheme to wss:// (or http:// to ws:// for an approved local test), retaining the host and configured path. Do not pass an HTTPS URL directly to a WebSocket constructor.
Send { "type": "ping", "id": "<data.id>", "claimedLocation": { "lat": 51.5074, "lon": -0.1278 } }.
On { "type": "pong" }, promptly send { "type": "ack" }. The operator measures this round trip.
Read { "type": "attestation", "attestation": ... }. Validate signer, chain, deployment, task, commitment, result and freshness before accepting it. See individual results.

Each witness submits an onchain response, which costs its operator Sepolia gas. A pong is not evidence of acceptance. The exchange can fail if the task is not yet cached, registration is incomplete or transaction submission fails. Set a timeout and surface failure; do not blindly resubmit a commitment after a network timeout.

Released SDK limitations

Use @offline-protocol/pol for Proof of Location. React Native 0.3.3 removes useProofOfLocation and React 0.2.0 removes useLocation. The hooks in older versions omit the required witness id and ignore attestation replies. Do not rely on them for witness evidence. The gateway now maps older SDKs’ x-project-id to X-App-Id. Direct API clients must send X-App-Id as shown above. Hosted usage-limit enforcement is active; header compatibility does not repair the older hooks’ witness exchange.

Handle errors

Status	Meaning
400	Invalid coordinates/request, or missing `x-app-id` when required.
401	Missing or invalid user authentication.
402	The application’s organization has its hosted services paused: a Free plan limit reached without a card, the Proof of Location billing limit reached, or a failed payment. The message names the cause. See usage warnings, billing limits and pauses.
403	Profile not owned by the caller, or `ACCOUNT_SUSPENDED` when the user’s account is suspended.
404	Profile not found.
429	Default commitment limit: 3 submissions per 60 seconds per user. Inspect `data.retry_after_seconds`.
500	Local service or dependency failure.
502	Upstream rejection or submission failure, including upstream product-policy 401/403 mapped by user-service.
503	Commitment or rate-limit service unavailable.
504	Upstream timeout. A transaction may already have been submitted.

The API maps other upstream 5xx responses to 502; it does not forward every upstream 500 unchanged.

​Use the SDK

​Submit with the raw API

​Witness exchange

​Released SDK limitations

​Handle errors

Use the SDK

Submit with the raw API

Witness exchange

Released SDK limitations

Handle errors