API Overview

REST APIs for geospatial operations and location records

Research Preview — This API specification is under development.

API Reference

Astral provides two REST APIs:

API	Purpose	Base URL
Compute API	Verifiable geospatial operations	/compute/v0
Records API	Query location attestations	/api/v0

Compute API

Distance, containment, proximity checks with signed attestations

Records API

Query existing location attestations across chains

---

Compute API

The Compute API performs verifiable geospatial operations and returns signed attestations.

Base URL

https://api.astral.global/compute/v0

Authentication

Phase 1 (MVP)

No authentication required. Rate limiting by IP address.

# No auth headers needed
curl https://api.astral.global/compute/v0/distance \
  -H "Content-Type: application/json" \
  -d '{"chainId": 84532, "from": "0xabc...", "to": "0xdef...", "schema": "0x..."}'

Phase 2 (Future)

Wallet-based authentication with signed requests.

curl https://api.astral.global/compute/v0/distance \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: 0x..." \
  -H "X-Signature: 0x..." \
  -d '...'

Input Types

All endpoints accept geometry inputs in these formats:

Format	Description	Example
UID string	Onchain attestation	"0xabc123..."
GeoJSON	Raw geometry	{"type": "Point", "coordinates": [2.29, 48.85]}
UID + URI	Offchain attestation	{"uid": "0xabc...", "uri": "ipfs://Qm..."}
Inline attestation	Full offchain object	{"attestation": {...}}

Response Format

All successful responses include:

{
  "result": 523.45,
  "units": "meters",
  "operation": "distance",
  "timestamp": 1706400000,
  "inputRefs": ["0x...", "0x..."],
  "attestation": {
    "schema": "0x...",
    "attester": "0x...",
    "recipient": "0x...",
    "data": "0x...",
    "signature": "0x..."
  },
  "delegatedAttestation": {
    "signature": "0x...",
    "attester": "0x...",
    "deadline": 1706403600
  }
}

Error Format

Errors follow RFC 7807 (Problem Details for HTTP APIs):

{
  "type": "https://api.astral.global/errors/attestation-not-found",
  "title": "Attestation Not Found",
  "status": 404,
  "detail": "Location attestation with UID 0xabc123... not found on chain 84532"
}

Error Types

Type	Status	Description
invalid-input	400	Bad request data, missing fields, invalid geometry
attestation-not-found	404	UID doesn’t exist on specified chain
verification-failed	401	Signature verification failed
computation-error	500	PostGIS operation failed
rate-limited	429	Too many requests

Rate Limits

Auth Level	Limit
Unauthenticated	100 requests/hour per IP
Wallet authenticated	1000 requests/hour

During development and testing, you may hit rate limits quickly. Consider caching results or using a test wallet for higher limits.

Chain Configuration

The following table shows addresses for supported chains. The Attester Address is the address that signs delegated attestations—resolver contracts must verify attestations come from this address.

Chain	Chain ID	EAS	Schema Registry	Attester Address
Base Sepolia	84532	0x4200000000000000000000000000000000000021	0x4200000000000000000000000000000000000020	0x590fdb53ed3f0B52694876d42367192a5336700F

Available Endpoints

POST /distance

Distance between two geometries

POST /contains

Is geometry B inside geometry A?

POST /within

Is point within radius of target?

POST /intersects

Do geometries overlap?

POST /area

Area of a polygon

POST /length

Length of a line