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

​
API reference

Astral provides two REST APIs for working with location proofs and geospatial data:
APIPurposeBase URL
Verify APIVerify location proofs and stamps/verify/v0
Compute APIVerifiable geospatial operations/compute/v0
The Records API (query location attestations across chains) is not yet integrated into the service. See the roadmap for timeline.

Verify API

Verify stamps, evaluate proofs, list plugins

Compute API

Distance, containment, proximity checks with signed attestations

​
Base URLs

https://staging-api.astral.global/verify/v0
https://staging-api.astral.global/compute/v0

​
Authentication

All requests require an API key, passed as a header: 
# Either header works
-H "X-API-Key: your-api-key"
-H "Authorization: Bearer your-api-key"

​
Rate limits

TierLimitHow to get
Public100 requests/hourDefault — no signup required
Developer1,000 requests/hourRequest a developer key
Internal10,000 requests/hourAstral team only
Rate limit headers are included in every response: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1706403600

​
Input types

All compute endpoints accept geometry inputs in these formats:
FormatDescriptionExample
Onchain UIDOnchain attestation reference{"uid": "0xabc123..."}
GeoJSONRaw geometry{"type": "Point", "coordinates": [2.29, 48.85]}
UID + URIOffchain attestation (not yet implemented){"uid": "0xabc...", "uri": "ipfs://Qm..."}
Verified proofFull verified proof response object{"verifiedProof": { ... }}
See Input for the full type definition.

​
Response format

​
Numeric operations (distance, area, length)

{
  "result": 523.45,
  "units": "meters",
  "operation": "distance",
  "timestamp": 1706400000,
  "inputRefs": ["0x...", "0x..."],
  "attestation": {
    "schema": "0x...",
    "attester": "0x...",
    "recipient": "0x...",
    "data": "0x...",
    "revocable": true,
    "refUID": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "signature": "0x..."
  },
  "delegatedAttestation": {
    "signature": "0x...",
    "attester": "0x...",
    "deadline": 1706403600,
    "nonce": 0
  }
}
See NumericComputeResponse and BooleanComputeResponse for the full type definitions.

​
Boolean operations (contains, within, intersects)

Same shape, but result is true/false and there is no units field.

​
Error format

Errors follow RFC 7807 (Problem Details for HTTP APIs): 
{
  "type": "https://astral.global/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "geometry field is required"
}

​
Error types

TypeStatusDescription
bad-request400Malformed request body
invalid-input400Bad request data, missing fields, invalid geometry
validation400Input validation failed
unauthorized401Invalid or missing API key
not-implemented501Requested operation or plugin not yet supported
internal500Internal server error
database500Database operation failed
rate-limited429Too many requests — check rate limit headers

​
Chain configuration

The Attester Address is the address that signs delegated attestations. Resolver contracts must verify attestations come from this address.
ChainChain IDEASSchema RegistryAttester Address
Base Sepolia845320x42000000000000000000000000000000000000210x42000000000000000000000000000000000000200x590fdb53ed3f0B52694876d42367192a5336700F

​
Endpoints

​
Verify API

POST /verify/v0/stamp

Verify a single stamp’s internal validity

POST /verify/v0/proof

Verify a proof with cross-correlation analysis

GET /verify/v0/plugins

List available verification plugins

​
Compute API

POST /compute/v0/distance

Distance between two geometries

POST /compute/v0/area

Area of a polygon

POST /compute/v0/length

Length of a line

POST /compute/v0/contains

Is geometry B inside geometry A?

POST /compute/v0/within

Is point within radius of target?

POST /compute/v0/intersects

Do geometries overlap?