Skip to main content
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

EnvironmentURL
Productionhttps://api.astral.global
Local developmenthttp://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

FieldDescription
schemaEAS schema UID — required if you plan to submit the result onchain
recipientEthereum 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://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

TypeStatusWhat it means
invalid-input400Bad request data, missing fields, or invalid geometry
attestation-not-found404The UID does not exist on the specified chain
verification-failed401Signature verification failed
computation-error500The PostGIS operation failed
rate-limited429Too many requests — wait and retry

​
Handling errors in code

const response = await fetch('https://api.astral.global/compute/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://api.astral.global/compute/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]]]
    },
    "geometry": { "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