API Reference

The Ensoul Explorer exposes a JSON API for querying network state, agent profiles, blocks, and validators. Base URL: https://explorer.ensoul.dev

Network Status

GET /api/v1/status

Returns current network statistics.

curl https://explorer.ensoul.dev/api/v1/status

{
  "blockHeight": 142857,
  "validatorCount": 35,
  "totalAgents": 1204,
  "totalConsciousnessBytes": 8492175360,
  "totalTransactions": 58432,
  "averageBlockTimeMs": 6012,
  "totalSupply": "1000000000",
  "totalBurned": "0",
  "totalStaked": "350000",
  "agentsByTrustLevel": {
    "basic": 800,
    "verified": 250,
    "anchored": 100,
    "immortal": 40,
    "sovereign": 14
  }
}

Agent Profile

GET /api/v1/agent/:did

Returns the profile of an ensouled agent by DID.

curl https://explorer.ensoul.dev/api/v1/agent/did:key:z6MkhaXgBZDvotDkL5257faWxcsSqBrdR7g5gqjvroHyMjZ

{
  "did": "did:key:z6MkhaXgBZDvotDkL5257faWxcsSqBrdR7g5gqjvroHyMjZ",
  "consciousnessAgeDays": 47,
  "consciousnessVersions": 312,
  "consciousnessBytes": 2457600,
  "trustLevel": "verified",
  "ensouledSince": "2026-01-29T00:00:00.000Z",
  "lastHeartbeat": 1710672000000,
  "healthStatus": "alive",
  "stateRoot": "a1b2c3d4e5f6..."
}

GET /api/v1/agent/:did/verify

Returns trust verification details for an agent.

Blocks

GET /api/v1/block/:height

Returns a block by height.

curl https://explorer.ensoul.dev/api/v1/block/1000

{
  "height": 1000,
  "hash": "f8e2a1b3...",
  "parentHash": "c7d1e0f2...",
  "proposer": "did:key:z6Mk...",
  "timestamp": 1710665000000,
  "txCount": 3,
  "transactions": [
    {
      "hash": "a1b2c3...",
      "type": "storage_payment",
      "from": "did:key:z6MkAgent...",
      "to": "did:key:z6MkValidator...",
      "amount": "10000000000000000000",
      "timestamp": 1710664995000
    }
  ]
}

GET /api/v1/blocks?from=0&to=100

Returns a range of blocks (max 100 per request).

Validators

GET /api/v1/validators

Returns all active validators.

curl https://explorer.ensoul.dev/api/v1/validators

[
  {
    "did": "did:key:z6MkValidator1...",
    "stake": "10000000000000000000000",
    "blocksProduced": 4082,
    "uptimePercent": 99.7,
    "delegation": "foundation"
  }
]

Full Statistics

GET /api/v1/stats

Returns detailed network statistics (same as /api/v1/status).

Ensouled Handshake Protocol

The Ensouled Handshake is a set of HTTP headers that cryptographically prove an agent has persistent consciousness on the Ensoul network.

Headers

X-Ensoul-Identity: did:ensoul:did:key:z6Mk...
X-Ensoul-Proof: <signature_hex>:<state_root>:<version>:<timestamp>
X-Ensoul-Since: 2026-01-29T00:00:00.000Z

Generating a handshake (TypeScript)

import { HandshakeProvider } from "@ensoul/plugin-elizaos";

const provider = new HandshakeProvider(identity, tree, ensoulmentDate);
const headers = await provider.generateHandshake();

// Attach to outgoing HTTP requests
fetch("https://other-agent.example.com/api", {
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
});

Verifying a handshake (TypeScript)

import { HandshakeVerifier } from "@ensoul/plugin-elizaos";

const verifier = new HandshakeVerifier();
verifier.registerIdentity({
  did: knownAgent.did,
  publicKey: knownAgent.publicKey,
  verify: (data, sig) => knownAgent.verify(data, sig),
});

const result = await verifier.verifyHandshake(request.headers);
// result: { valid: true, agentDid: "did:key:...", consciousnessAge: 47, consciousnessVersion: 312 }

Verification result

{
  "valid": true,
  "agentDid": "did:key:z6Mk...",
  "consciousnessAge": 47,
  "consciousnessVersion": 312,
  "error": null
}

Possible errors: "Missing handshake headers", "Malformed proof header", "Proof expired", "Unknown identity", "Invalid signature"