Attestor API Reference

Complete API reference for the L{CORE} Attestor service.

---

Base URL

Environment	URL
Local	http://localhost:8001
Production	http://${ATTESTOR_IP}:8001

---

Health & Status

Health Check

GET /healthcheck

Response:

{
  "status": "ok",
  "version": "5.0.0",
  "lcore_enabled": true
}

L{CORE} Status

GET /api/lcore/status

Response:

{
  "success": true,
  "data": {
    "enabled": true,
    "cartesiConnected": true,
    "dappAddress": "0xAE0863401D5B953b89cad8a5E7c98f5136E9C26d"
  }
}

L{CORE} Health

GET /api/lcore/health

Response:

{
  "success": true,
  "data": {
    "attestor": "healthy",
    "cartesi": "healthy",
    "blockchain": "connected"
  }
}

---

Provider Schemas

List All Schemas

GET /api/lcore/schemas

Response:

{
  "success": true,
  "data": [
    {
      "schema_id": "coingecko-btc-price",
      "name": "CoinGecko BTC Price",
      "description": "Bitcoin price from CoinGecko API",
      "provider_type": "http"
    }
  ]
}

Get Schema by ID

GET /api/lcore/schemas/:schemaId

Parameters:

Parameter	Type	Description
schemaId	string	Unique schema identifier

Response:

{
  "success": true,
  "data": {
    "schema_id": "coingecko-btc-price",
    "name": "CoinGecko BTC Price",
    "description": "Bitcoin price from CoinGecko API",
    "provider_type": "http",
    "bucket_definitions": {
      "price": {
        "boundaries": [0, 10000, 25000, 50000, 100000],
        "labels": ["<10k", "10k-25k", "25k-50k", "50k-100k", ">100k"]
      }
    }
  }
}

Register Schema

POST /api/lcore/provider-schema

Headers:

Authorization: Bearer <admin_token>
Content-Type: application/json

Body:

{
  "provider": "chase",
  "flowType": "web_request",
  "domain": "lending",
  "bucketDefinitions": {
    "balance": {
      "boundaries": [0, 1000, 5000, 10000, 25000, 50000, 100000],
      "labels": ["<1k", "1k-5k", "5k-10k", "10k-25k", "25k-50k", ">50k"]
    }
  },
  "dataKeys": ["parameters", "context"],
  "freshnessHalfLife": 604800
}

Response:

{
  "success": true,
  "data": {
    "schema_id": "chase-lending"
  }
}

---

Encryption Keys

Register Encryption Key

POST /api/lcore/encryption-key

Headers:

Authorization: Bearer <admin_token>
Content-Type: application/json

Body:

{
  "publicKey": "base64-encoded-nacl-public-key",
  "algorithm": "nacl-box"
}

Response:

{
  "success": true,
  "data": {
    "keyId": "key-abc123"
  }
}

---

Attestations

Create Attestation

POST /api/lcore/claim

Headers:

Content-Type: application/json

Body:

{
  "provider": "http",
  "params": {
    "url": "https://api.example.com/data",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer token"
    }
  },
  "bucketDefinition": {
    "field": "balance",
    "boundaries": [0, 1000, 10000],
    "labels": ["low", "medium", "high"]
  }
}

Response:

{
  "success": true,
  "data": {
    "claimId": "claim-xyz789",
    "txHash": "0x...",
    "bucket": "medium"
  }
}

Get Attestation

GET /api/lcore/attestation/:claimId

Parameters:

Parameter	Type	Description
claimId	string	Attestation claim ID

Response:

{
  "success": true,
  "data": {
    "claimId": "claim-xyz789",
    "provider": "http",
    "bucket": "medium",
    "timestamp": 1704067200,
    "owner": "0x1234..."
  }
}

List User Attestations

GET /api/lcore/attestations/:address

Parameters:

Parameter	Type	Description
address	string	Ethereum address

Response:

{
  "success": true,
  "data": [
    {
      "claimId": "claim-xyz789",
      "provider": "http",
      "bucket": "medium",
      "timestamp": 1704067200
    }
  ]
}

---

Access Grants

Grant Access

POST /api/lcore/grant

Headers:

Authorization: Bearer <user_token>
Content-Type: application/json

Body:

{
  "requester": "0x5678...",
  "schemaId": "chase-lending",
  "expiresAt": 1735689600
}

Response:

{
  "success": true,
  "data": {
    "grantId": "grant-abc123",
    "txHash": "0x..."
  }
}

Revoke Access

DELETE /api/lcore/grant/:grantId

Headers:

Authorization: Bearer <user_token>

Response:

{
  "success": true
}

Check Access

GET /api/lcore/access/:owner/:requester

Parameters:

Parameter	Type	Description
owner	string	Data owner address
requester	string	Requesting address

Response:

{
  "success": true,
  "data": {
    "hasAccess": true,
    "grants": [
      {
        "grantId": "grant-abc123",
        "schemaId": "chase-lending",
        "expiresAt": 1735689600
      }
    ]
  }
}

---

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Malformed request body
UNAUTHORIZED	401	Missing or invalid auth token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
PROVIDER_ERROR	502	External provider failed
CARTESI_ERROR	503	Cartesi node unavailable
INTERNAL_ERROR	500	Unexpected server error

---

WebSocket API

Connection

const ws = new WebSocket('ws://${ATTESTOR_IP}:8001/ws')

Events

attestation:created

Fired when a new attestation is created.

{
  "event": "attestation:created",
  "data": {
    "claimId": "claim-xyz789",
    "owner": "0x1234...",
    "provider": "http"
  }
}

grant:created

Fired when access is granted.

{
  "event": "grant:created",
  "data": {
    "grantId": "grant-abc123",
    "owner": "0x1234...",
    "requester": "0x5678..."
  }
}

---

Rate Limits

Endpoint	Limit
Health checks	100/min
Schema reads	60/min
Attestations	10/min
Grants	20/min

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067260