Research Preview — This API specification is under development.

API reference

Astral provides two REST APIs for working with location proofs and geospatial data:

API	Purpose	Base URL
Verify API	Verify location proofs and stamps	`/verify/v0`
Compute API	Verifiable 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

The hosted staging service is currently open: the public tier needs no API key. Supplying an API key as a header raises your rate limit:

# Either header works
-H "X-API-Key: your-api-key"
-H "Authorization: Bearer your-api-key"

Rate limits

Tier	Limit	How to get
Public	100 requests/hour	Default — no API key required
Developer	1,000 requests/hour	Email contact@astral.global for a key
Internal	10,000 requests/hour	Astral team only

Rate-limit tiers are an evolving part of the Research Preview. The public tier is open today; authenticated tiers are being rolled out.

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:

Format	Description	Example
Onchain UID	Onchain attestation reference	`{"uid": "0xabc123..."}`
GeoJSON	Raw geometry	`{"type": "Point", "coordinates": [2.29, 48.85]}`
UID + URI	Offchain attestation (not yet implemented)	`{"uid": "0xabc...", "uri": "ipfs://Qm..."}`
Verified proof	Full 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

Type	Status	Description
`bad-request`	400	Malformed request body
`invalid-input`	400	Bad request data, missing fields, invalid geometry
`validation`	400	Input validation failed
`unauthorized`	401	Invalid or missing API key
`not-implemented`	501	Requested operation or plugin not yet supported
`internal`	500	Internal server error
`database`	500	Database operation failed
`rate-limited`	429	Too 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.

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

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?

API Reference

API Overview

API reference

Verify API

Compute API

Base URLs

Authentication

Rate limits

Input types

Response format

Numeric operations (distance, area, length)

Boolean operations (contains, within, intersects)

Error format

Error types

Chain configuration

Endpoints

Verify API

POST /verify/v0/stamp

POST /verify/v0/proof

GET /verify/v0/plugins

Compute API

POST /compute/v0/distance

POST /compute/v0/area

POST /compute/v0/length

POST /compute/v0/contains

POST /compute/v0/within

POST /compute/v0/intersects

​API reference

Verify API

Compute API

​Base URLs

​Authentication

​Rate limits

​Input types

​Response format

​Numeric operations (distance, area, length)

​Boolean operations (contains, within, intersects)

​Error format

​Error types

​Chain configuration

​Endpoints

​Verify API

POST /verify/v0/stamp

POST /verify/v0/proof

GET /verify/v0/plugins

​Compute API

POST /compute/v0/distance

POST /compute/v0/area

POST /compute/v0/length

POST /compute/v0/contains

POST /compute/v0/within

POST /compute/v0/intersects

API reference

Base URLs

Authentication

Rate limits

Input types

Response format

Numeric operations (distance, area, length)

Boolean operations (contains, within, intersects)

Error format

Error types

Chain configuration

Endpoints

Verify API

Compute API