Introduction

How to choose between IXO Protocol APIs and IXO service APIs.

Use this page to select the right API surface before implementation.

Vocabulary

  • Protocol gateways — Node-level interfaces to IXO Protocol modules: submit and query chain state via JSON-RPC or REST over gRPC (Cosmos stack). You typically need a wallet or signer for writes.
  • Service APIs — Operator-hosted interfaces over indexed chain data, Matrix, registry workflows, or USSD sessions. Auth and base URLs are deployment-specific; never assume one header works everywhere.

Comparison matrix

Blockchain RPC API
Blockchain REST API (gRPC gateway)
  • Primary purpose: HTTP/JSON queries (and tx broadcast where exposed)
  • Typical operations: Module REST paths, Swagger/OpenAPI per deployment
  • Read / write: Read; write depends on deployment
  • Auth and endpoints: Same as RPC—confirm with node operator
  • Docs: REST (gRPC gateway)
IXO Blocksync GraphQL API
  • Primary purpose: Indexed queries over chain-derived entities
  • Typical operations: GraphQL queries (subscriptions if enabled)
  • Read / write: Read-only in docs model
  • Auth and endpoints: Service operator credentials
  • Docs: Blocksync GraphQL API
Matrix state bot API
  • Primary purpose: Room state, ACLs, automation hooks for Matrix
  • Typical operations: Bot-specific HTTP endpoints
  • Read / write: Read + write (room operations)
  • Auth and endpoints: Service operator credentials
  • Docs: Matrix state bot API
Registry API
  • Primary purpose: Impact Hub Registry application workflows
  • Typical operations: CRUD-style registry operations per spec
  • Read / write: Read + write (per spec)
  • Auth and endpoints: Often Basic or bearer—confirm matrix
  • Docs: Registry API
USSD gateway API
  • Primary purpose: Telecom session bridge for USSD menus
  • Typical operations: Session request/response
  • Read / write: Write (session replies) + read patterns per spec
  • Auth and endpoints: Service operator policy
  • Docs: USSD gateway API

For SDK and product naming, see Product and SDK map.

Authentication and endpoints

This page does not define canonical auth headers or endpoint literals.

Authentication matrix

Use canonical auth requirements and literals by interface.

Networks and endpoints

Confirm network-specific endpoint mappings before implementation.

Product and SDK map

Navigate IXO products, APIs, and SDK references.

Next steps

API index

Compare protocol and service interfaces from one entry point.

Error handling

Handle API and transport failures consistently.

Pagination

Apply cursor and page patterns for large result sets.