Research Preview — APIs may change. GitHub

Calling the API

This guide covers the mechanics of making requests to Astral — how to format inputs, what comes back, and how to handle errors.

Base URL

Environment	URL
Staging (testnet)	`https://staging-api.astral.global`
Local development	`http://localhost:3004`

See Local development for setup instructions.

Request format

All compute endpoints accept POST requests with a JSON body. The required fields depend on the operation, but every request needs a chainId to identify which chain to sign for.

Distance, length

{
  "from": { "type": "Point", "coordinates": [2.2945, 48.8584] },
  "to": { "type": "Point", "coordinates": [2.3522, 48.8566] },
  "chainId": 84532
}

Contains, intersects

{
  "container": {
    "type": "Polygon",
    "coordinates": [[[2.28, 48.85], [2.30, 48.85], [2.30, 48.87], [2.28, 48.87], [2.28, 48.85]]]
  },
  "geometry": { "type": "Point", "coordinates": [2.2945, 48.8584] },
  "chainId": 84532
}

Optional fields

Field	Description
`schema`	EAS schema UID — required if you plan to submit the result onchain
`recipient`	Ethereum address to set as the attestation recipient

Geographic feature inputs

You can pass geographic features in four formats:

Raw GeoJSON

A GeoJSON geometry object directly in the request:

{
  "from": { "type": "Point", "coordinates": [2.2945, 48.8584] }
}

UID string

A reference to an onchain location attestation:

{
  "from": "0xabc123...def456"
}

UID + URI (offchain attestation)

A reference to an offchain attestation stored on IPFS or another location:

{
  "from": { "uid": "0xabc123...", "uri": "ipfs://Qm..." }
}

Inline signed attestation

A full offchain attestation object:

{
  "from": { "attestation": { "uid": "0x...", "schema": "0x...", "data": "0x..." } }
}

Authentication

No authentication is currently required. Rate limits apply by IP address (100 requests/hour for unauthenticated clients). Wallet-based authentication with higher limits is planned.

Response format

A successful response includes the computed result, proof of computation, and a pre-signed attestation for optional onchain submission.

{
  "result": 4520.37,
  "units": "meters",
  "operation": "distance",
  "timestamp": 1706400000,
  "inputRefs": [
    "0xabc123...input_a_hash",
    "0xdef456...input_b_hash"
  ],
  "attestation": {
    "uid": "0x...",
    "schema": "0x...",
    "attester": "0x...",
    "recipient": "0x...",
    "data": "0x...",
    "signature": "0x..."
  },
  "delegatedAttestation": {
    "signature": "0x7f8e9d...tee_signature",
    "attester": "0x590fdb53ed3f0B52694876d42367192a5336700F",
    "deadline": 1706403600
  }
}

Here is what each field means:

result — The computed answer. A number for distance/area/length, a boolean for contains/within/intersects.
units — Unit of measurement (for numeric results). "meters" or "square_meters".
operation — The spatial operation that was performed.
timestamp — Unix timestamp of when the computation ran.
inputRefs — Hashes of the input geographic features. These let you verify which inputs were used in the computation.
attestation — The full EAS attestation data, including the TEE’s cryptographic signature.
delegatedAttestation — A pre-signed attestation ready for onchain submission via EAS. The deadline indicates when the signature expires.

Error handling

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

{
  "type": "https://staging-api.astral.global/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Field 'from' must be a valid GeoJSON geometry or attestation UID"
}

Common error types

Type	Status	What it means
`invalid-input`	400	Bad request data, missing fields, or invalid geometry
`attestation-not-found`	404	The UID does not exist on the specified chain
`verification-failed`	401	Signature verification failed
`computation-error`	500	The PostGIS operation failed
`rate-limited`	429	Too many requests — wait and retry

Handling errors in code

const response = await fetch('https://staging-api.astral.global/compute/v0/distance', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: { type: 'Point', coordinates: [2.2945, 48.8584] },
    to: { type: 'Point', coordinates: [2.3522, 48.8566] },
    chainId: 84532
  })
});

if (!response.ok) {
  const error = await response.json();
  console.error(`${error.title}: ${error.detail}`);
  return;
}

const result = await response.json();
console.log(`Distance: ${result.result} ${result.units}`);

Full example: curl

curl -X POST https://staging-api.astral.global/compute/v0/contains \
  -H "Content-Type: application/json" \
  -d '{
    "container": {
      "type": "Polygon",
      "coordinates": [[[2.28, 48.85], [2.30, 48.85], [2.30, 48.87], [2.28, 48.87], [2.28, 48.85]]]
    },
    "containee": { "type": "Point", "coordinates": [2.2945, 48.8584] },
    "chainId": 84532
  }'

Next steps

Agent integration

Use Astral as a spatial oracle in agent workflows

Blockchain integration

Submit signed results onchain via EAS

API reference

Full endpoint documentation

​Calling the API

​Base URL

​Request format

​Distance, length

​Contains, intersects

​Optional fields

​Geographic feature inputs

​Raw GeoJSON

​UID string

​UID + URI (offchain attestation)

​Inline signed attestation

​Authentication

​Response format

​Error handling

​Common error types

​Handling errors in code

​Full example: curl

​Next steps

Agent integration

Blockchain integration

API reference

Calling the API

Base URL

Request format

Distance, length

Contains, intersects

Optional fields

Geographic feature inputs

Raw GeoJSON

UID string

UID + URI (offchain attestation)

Inline signed attestation

Authentication

Response format

Error handling

Common error types

Handling errors in code

Full example: curl

Next steps