Skip to main content
Research Preview — This API is under development.

​
Verify proof

Verify a location proof (a claim bundled with one or more stamps). This endpoint verifies each stamp individually, then cross-correlates them to produce a CredibilityVector — a multidimensional assessment of how well the evidence supports the claim. 
POST /verify/v0/proof
The Verify API does not return a single summary score. The CredibilityVector provides spatial, temporal, validity, and independence dimensions so your application can define its own trust model.

​
Request body

​
proof
LocationProof
required
The proof to verify. Contains a claim (LocationClaim) and an array of stamps (LocationStamp).
​
options.chainId
number
Chain ID for EAS attestation signing (e.g., 84532 for Base Sepolia).
​
options.submitOnchain
boolean
Whether to submit the attestation onchain. Defaults to false.

​
Example request

curl -X POST https://api.astral.global/verify/v0/proof \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "proof": {
      "claim": {
        "lpVersion": "0.2",
        "locationType": "geojson-point",
        "location": { "type": "Point", "coordinates": [-122.4194, 37.7749] },
        "srs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
        "subject": { "scheme": "eth-address", "value": "0x1234..." },
        "radius": 100,
        "time": { "start": 1706900000, "end": 1706903600 }
      },
      "stamps": [
        {
          "lpVersion": "0.2",
          "locationType": "geojson-point",
          "location": { "type": "Point", "coordinates": [-122.4195, 37.7750] },
          "srs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
          "temporalFootprint": { "start": 1706901000, "end": 1706901060 },
          "plugin": "proofmode",
          "pluginVersion": "0.1.0",
          "signals": {},
          "signatures": [{ "signer": { "scheme": "device-pubkey", "value": "0x..." }, "algorithm": "secp256k1", "value": "0x...", "timestamp": 1706901030 }]
        },
        {
          "lpVersion": "0.2",
          "locationType": "geojson-point",
          "location": { "type": "Point", "coordinates": [-122.4193, 37.7748] },
          "srs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
          "temporalFootprint": { "start": 1706901000, "end": 1706901120 },
          "plugin": "witnesschain",
          "pluginVersion": "0.1.0",
          "signals": {},
          "signatures": [{ "signer": { "scheme": "eth-address", "value": "0x..." }, "algorithm": "secp256k1", "value": "0x...", "timestamp": 1706901060 }]
        }
      ]
    },
    "options": {
      "chainId": 84532
    }
  }'

​
Response

The response contains the verified proof, a credibility vector, and optional EAS attestation data.
​
proof
LocationProof
required
The verified proof object.
​
credibility
CredibilityVector
required
Multidimensional assessment of how well the stamps support the claim. See CredibilityVector for the full type.
​
evaluationMethod
string
required
The evaluation method used (e.g., "multifactor-v0").
​
evaluatedAt
number
required
Unix timestamp (seconds) of when the evaluation was performed.
​
attestation
AttestationData
EAS attestation data. Present when chainId is provided. See AttestationData.
​
delegatedAttestation
DelegatedAttestationData
Delegated attestation for onchain submission. See DelegatedAttestationData.

​
Example response

{
  "proof": {
    "claim": { "..." : "..." },
    "stamps": ["..."]
  },
  "credibility": {
    "dimensions": {
      "spatial": {
        "meanDistanceMeters": 12.5,
        "maxDistanceMeters": 18.3,
        "withinRadiusFraction": 1.0
      },
      "temporal": {
        "meanOverlap": 0.95,
        "minOverlap": 0.90,
        "fullyOverlappingFraction": 0.5
      },
      "validity": {
        "signaturesValidFraction": 1.0,
        "structureValidFraction": 1.0,
        "signalsConsistentFraction": 1.0
      },
      "independence": {
        "uniquePluginRatio": 1.0,
        "spatialAgreement": 0.88,
        "pluginNames": ["proofmode", "witnesschain"]
      }
    },
    "stampResults": [
      {
        "stampIndex": 0,
        "plugin": "proofmode",
        "signaturesValid": true,
        "structureValid": true,
        "signalsConsistent": true,
        "distanceMeters": 12.5,
        "temporalOverlap": 0.95,
        "withinRadius": true,
        "details": {
          "hashVerified": true,
          "certificateChainValid": true
        }
      },
      {
        "stampIndex": 1,
        "plugin": "witnesschain",
        "signaturesValid": true,
        "structureValid": true,
        "signalsConsistent": true,
        "distanceMeters": 18.3,
        "temporalOverlap": 0.90,
        "withinRadius": true,
        "details": {
          "latencyVerified": true,
          "nodeCount": 3
        }
      }
    ],
    "meta": {
      "stampCount": 2,
      "evaluatedAt": 1706961600,
      "evaluationMode": "local"
    }
  },
  "evaluationMethod": "multifactor-v0",
  "evaluatedAt": 1706961600,
  "attestation": {
    "uid": "0xdef456...",
    "schema": "0x...",
    "attester": "0x590fdb53ed3f0B52694876d42367192a5336700F",
    "recipient": "0x1234...",
    "data": "0x...",
    "revocable": true,
    "refUID": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "signature": "0x..."
  },
  "delegatedAttestation": {
    "signature": "0x...",
    "attester": "0x590fdb53ed3f0B52694876d42367192a5336700F",
    "deadline": 1706403600,
    "nonce": 0
  }
}

​
Credibility vector

The credibility field is a CredibilityVector with four dimension groups:

​
dimensions.spatial

How close each stamp’s observed location is to the claimed location.
FieldTypeDescription
meanDistanceMetersnumberAverage distance between stamp locations and claimed location
maxDistanceMetersnumberLargest distance from any stamp to the claim
withinRadiusFractionnumberFraction of stamps within the claim’s radius (0-1)

​
dimensions.temporal

How well each stamp’s temporal footprint overlaps with the claimed time window.
FieldTypeDescription
meanOverlapnumberAverage temporal overlap ratio (0-1)
minOverlapnumberSmallest overlap of any stamp
fullyOverlappingFractionnumberFraction of stamps fully within the claim’s time window

​
dimensions.validity

Fraction of stamps passing each verification check.
FieldTypeDescription
signaturesValidFractionnumberFraction with valid signatures (0-1)
structureValidFractionnumberFraction with valid structure (0-1)
signalsConsistentFractionnumberFraction with consistent signals (0-1)

​
dimensions.independence

How independent and corroborative the evidence sources are.
FieldTypeDescription
uniquePluginRationumberRatio of unique plugins to total stamps (0-1)
spatialAgreementnumberHow well stamps agree spatially (0-1)
pluginNamesstring[]List of plugins that contributed stamps

​
stampResults

Per-stamp verification results. See StampResult for the full type.

​
meta

FieldTypeDescription
stampCountnumberNumber of stamps evaluated
evaluatedAtnumberUnix timestamp (seconds)
evaluationModestringEvaluation mode: "local", "tee", or "zk"

​
Errors

Errors follow RFC 7807:
TypeStatusDescription
invalid-input400Malformed proof, missing claim fields
validation400Claim validation failed (e.g., missing radius)
not-implemented501Plugin not supported
internal500Internal verification error
rate-limited429Too many requests
unauthorized401Invalid or missing API key

SDK: Verify

See the SDK documentation for client-side usage