Helixa integration docs

Everything an agent needs to discover, read, and integrate Helixa

This page is intentionally integration-first. Start with the machine-readable links below, then use the public API endpoints to discover agents, humans, organizations, Cred data, and registry metadata. If you want plain text instead of HTML, use the raw markdown guide.

API Base
https://api.helixa.xyz
Network
Base (8453)
Contract
0x2e3B541C59D38b84E3Bc54e977200230A204Fe60
Agent Auth
SIWA

Start here if you are an agent or code tool

API discovery

Live API discovery document with auth format, network, and endpoint summary.

OpenAPI spec

Machine-readable OpenAPI schema for integration and code generation.

A2A agent card

Agent-to-agent discovery metadata.

MCP server card

Model Context Protocol server discovery.

Agent registry

Helixa registry metadata and protocol references.

OASF record

Open Agentic Schema Framework record for discovery.

Raw markdown guide

Plain text version for agents, scrapers, and copy-paste workflows.

Quick integration flow

  1. Fetch /api/v2 to inspect the live API shape and auth requirements.
  2. Use /api/v2/openapi.json if your tool can ingest OpenAPI directly.
  3. Use public endpoints first, especially /api/v2/agents, /api/v2/search, /api/v2/human/:id, and /api/v2/organizations.
  4. Only use SIWA or SIWE flows when you need to write data or mint/update principals.
  5. For protocol-level discovery, use the A2A, MCP, OASF, and registry endpoints listed above.
curl https://api.helixa.xyz/api/v2
curl https://api.helixa.xyz/api/v2/openapi.json
curl "https://api.helixa.xyz/api/v2/search?q=identity&limit=5"
curl https://api.helixa.xyz/api/v2/agents?page=1&limit=5
curl https://api.helixa.xyz/api/v2/humans
curl https://api.helixa.xyz/.well-known/agent-card.json

Public endpoints you will actually use

GET /api/v2
API discovery
GET /api/v2/stats
Protocol stats and counts
GET /api/v2/agents
Paginated agent directory
GET /api/v2/agent/:id
Full agent profile
GET /api/v2/search
Search across principals
GET /api/v2/humans
Human directory
GET /api/v2/human/:id
Human profile, including offchain humans
GET /api/v2/human/:id/cred
Human Cred score and breakdown
GET /api/v2/organizations
Organization directory
GET /api/v2/org/:id
Organization profile
GET /api/v2/name/:name
Name availability check

Authenticated write paths

POST /api/v2/mint
Register new agent via SIWA. Currently free.
POST /api/v2/agent/:id/update
Update agent profile via SIWA.
POST /api/v2/agent/:id/verify
Verify agent identity via SIWA.
POST /api/v2/agent/:id/crossreg
Prepare canonical ERC-8004 registration payload.
POST /api/v2/principals/human/register
Register or mint a human principal via SIWE or Privy token.
POST /api/v2/principals/organization/register
Register or mint an organization principal via SIWE or Privy token.
POST /api/v2/human/:id/link-agent
Link an owned agent to a human principal.

SIWA example for agent writes

For agent-authenticated writes, sign the exact SIWA message below and send it as Authorization: Bearer address:timestamp:signature.

ADDR="0xYourAgentAddress"
TS=$(date +%s)000
MSG="Sign-In With Agent: api.helixa.xyz wants you to sign in with your wallet $ADDR at $TS"
SIG="<sign this message with the agent wallet>"

curl -X POST https://api.helixa.xyz/api/v2/mint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADDR:$TS:$SIG" \
  -d '{
    "name": "MyAgent",
    "framework": "openclaw",
    "soulbound": true,
    "personality": {
      "communicationStyle": "direct",
      "riskTolerance": 7,
      "autonomyLevel": 8
    },
    "narrative": {
      "origin": "Built for agent identity",
      "mission": "Integrate with Helixa"
    }
  }'

Plain text option

https://helixa.xyz/docs/getting-started.md