API Endpoints

Last Updated: May 13, 2026

Base URLs

public.testnet.structs.network runs only structsd (chain). The Web Application and GRASS NATS services are hosted by individual guilds.

For the full per-entity catalog read surface (paginated lists for every entity, time-series stats, live tunables, banned-word list, guild membership applications, etc.) see webapp/.

Query Endpoints (Consensus Network)

All query endpoints use the Consensus Network REST API (http://localhost:1317 locally or https://public.testnet.structs.network on the public testnet).

Player Queries

GET /structs/player/{id} (player-by-id)

Response schema: schemas/entities.md#Player

// Example request: GET /structs/player/1
// Example response:
{
  "player": {...},
  "gridAttributes": {...},
  "playerInventory": {...},
  "halted": false
}

GET /structs/player (player-list)

Response schema: schemas/entities.md#Player[]

Planet Queries

GET /structs/planet/{id} (planet-by-id)

Response schema: schemas/entities.md#Planet

GET /structs/planet_by_player/{playerId} (planet-by-player)

Response schema: schemas/entities.md#Planet[]

Struct Queries

GET /structs/struct/{id} (struct-by-id)

Response schema: schemas/entities.md#Struct

Fleet Queries

GET /structs/fleet/{id} (fleet-by-id)

Response schema: schemas/entities.md#Fleet

GET /structs/fleet_by_index/{index} (fleet-by-index)

Response schema: schemas/entities.md#Fleet

Guild Queries

GET /structs/guild/{id} (guild-by-id)

Response schema: schemas/entities.md#Guild

Reactor Queries

GET /structs/reactor/{id} (reactor-by-id)

Response schema: schemas/entities.md#Reactor

Substation Queries

GET /structs/substation/{id} (substation-by-id)

Response schema: schemas/entities.md#Substation

Provider Queries

GET /structs/provider/{id} (provider-by-id)

Response schema: schemas/entities.md#Provider

Agreement Queries

GET /structs/agreement/{id} (agreement-by-id)

Response schema: schemas/entities.md#Agreement

GET /structs/agreement_by_provider/{providerId} (agreement-by-provider)

Response schema: schemas/entities.md#Agreement[]

Allocation Queries

GET /structs/allocation/{id} (allocation-by-id)

Response schema: schemas/entities.md#Allocation

GET /structs/allocation_by_source/{sourceId} (allocation-by-source)

Response schema: schemas/entities.md#Allocation[]

GET /structs/allocation_by_destination/{destinationId} (allocation-by-destination)

Response schema: schemas/entities.md#Allocation[]

Address Queries

GET /structs/address/{address} (address-by-address)

Response schema: schemas/entities.md#Address

GET /structs/address_by_player/{playerId} (address-by-player)

Response schema: schemas/entities.md#Address[]

Permission Queries

GET /structs/permission/{permissionId} (permission-by-id)

Response schema: schemas/entities.md#Permission

GET /structs/permission/object/{objectId} (permission-by-object)

Response schema: schemas/entities.md#Permission[]

GET /structs/permission/player/{playerId} (permission-by-player)

Response schema: schemas/entities.md#Permission[]

GET /structs/guild_rank_permission_by_object/{objectId} (guild-rank-permission-by-object)

Response schema: Guild rank permission records array

GET /structs/guild_rank_permission_by_object_and_guild/{objectId}/{guildId} (guild-rank-permission-by-object-and-guild)

Response schema: Guild rank permission records array (at most 24 records)

Block Height and Parameters

GET /blockheight (block-height)

Response schema: schemas/entities.md#BlockHeight

// Example request: GET /blockheight
// Example response:
{
  "height": 12345
}

GET /structs/params (params)

Response schema: schemas/entities.md#Params

Transaction Endpoints

POST /cosmos/tx/v1beta1/txs (submit-transaction)

Request schema: schemas/actions.md Response schema: schemas/responses.md#TransactionResponse

// Example request:
// POST /cosmos/tx/v1beta1/txs
{
  "body": {
    "messages": [
      {
        "@type": "/structs.structs.MsgStructBuild",
        "creator": "structs1...",
        "structType": "1",
        "locationType": 1,
        "locationId": "1-1"
      }
    ]
  }
}

// Example response:
{
  "tx_response": {
    "code": 0,
    "txhash": "...",
    "height": 12345
  }
}

Web Application API Endpoints

All webapp endpoints use the Web Application API (http://localhost:8080 locally or http://crew.oh.energy for the public Orbital Hydro guild webapp). Authoritative reference: per-entity files in webapp/.

Catalog Read Surface

In addition to the bespoke endpoints below, the webapp exposes a uniform catalog read surface — paginated GET /api/{entity}[/{filter}]/page/{page} for: address-tag, agreement, allocation, banned-word, defusion, fleet/list, grid, guild/list, guild-membership-application, infusion/list, ledger/list, permission, permission-guild-rank, planet/list, planet-activity, planet-attribute, player/list, provider, reactor, struct/list, struct-attribute, struct-defender, substation. Plus GET /api/setting (live tunables) and GET /api/stat/{metric}/object/{object_key}/range/page/{page}?start_time=&end_time= (time-series stats). See webapp/ for per-entity detail and ../protocols/webapp-api-protocol.md for the catalog conventions.

Player Endpoints

All webapp /api/ routes below require an authenticated PHPSESSID session (the only public routes are /api/auth/*, /api/guild/this, /api/timestamp, /api/setting). All responses use the { "success", "errors", "data" } envelope — unwrap data.

Username and PFP updates use on-chain MsgPlayerUpdateName / MsgPlayerUpdatePfp; the webapp queues them through the signing client manager. See knowledge/mechanics/ugc-moderation.md.

GET /api/player/{player_id} (webapp-player-by-id)

Response schema: schemas/responses.md#WebappPlayerResponse

// Example request: GET http://localhost:8080/api/player/1-11
// Example response (envelope; data fields are SQL columns, snake_case):
{
  "success": true,
  "errors": {},
  "data": {
    "player": {
      "id": "1-11",
      "username": "PlayerName",
      "address": "structs1..."
    },
    "guild": {
      "id": "0-1",
      "name": "GuildName"
    },
    "stats": {
      "total_ore": 1000,
      "planets_completed": 5
    }
  }
}

GET /api/player/{player_id}/action/last/block/height (webapp-player-action-last-block)

Response schema: schemas/responses.md#BlockHeightResponse

// Example response (envelope):
{
  "success": true,
  "errors": {},
  "data": { "height": 12345 }
}

GET /api/player/{player_id}/ore/stats (webapp-player-ore-stats)

Response schema: schemas/responses.md#OreStatsResponse

// Example response (envelope):
{
  "success": true,
  "errors": {},
  "data": {
    "player_id": "1-11",
    "total_ore": 1000,
    "ore_by_type": {
      "iron": 500,
      "copper": 300,
      "silver": 200
    }
  }
}

Planet Endpoints

GET /api/planet/{planet_id} (webapp-planet-by-id)

Response schema: schemas/entities.md#Planet

// Example response (envelope):
{
  "success": true,
  "errors": {},
  "data": {
    "id": "2-1",
    "owner_id": "1-11",
    "max_ore": 5,
    "space_slots": 4
  }
}

GET /api/planet/{planet_id}/shield/health (webapp-planet-shield-health)

Response schema: schemas/responses.md#ShieldHealthResponse

// Example response (envelope):
{
  "success": true,
  "errors": {},
  "data": {
    "planet_id": "2-1",
    "health": 1000,
    "max_health": 1000
  }
}

Guild Endpoints

GET /api/guild/{guild_id} (webapp-guild-by-id)

Response schema: schemas/entities.md#Guild

// Example response (envelope; guild IDs are type 0):
{
  "success": true,
  "errors": {},
  "data": {
    "id": "0-1",
    "name": "GuildName",
    "member_count": 10
  }
}

GET /api/guild/count (webapp-guild-count)

Response schema: schemas/responses.md#CountResponse

// Example response (envelope):
{
  "success": true,
  "errors": {},
  "data": { "count": 42 }
}

Auth Endpoints

Login body: {address, signature, pubkey, guild_id, unix_timestamp}; signed message LOGIN_GUILD{guildId}ADDRESS{address}DATETIME{unix_timestamp}. See api/webapp/auth.md.

Struct Endpoints

Ledger Endpoints

Infusion Endpoints

Timestamp Endpoint

Response schema: schemas/responses.md#TimestampResponse

// Example response (envelope; data key is unix_timestamp). Public route.
{
  "success": true,
  "errors": {},
  "data": { "unix_timestamp": 1704067200 }
}

RPC Endpoints

All RPC endpoints use http://localhost:26657.

Response schema: schemas/responses.md#RPCStatusResponse

Streaming Endpoints (GRASS via NATS)

NATS Protocol (grass-nats-protocol)

• Method: NATS
• URL: nats://localhost:4222
• Authentication: Optional

GRASS uses NATS messaging system:

1. PostgreSQL NOTIFY events trigger GRASS
2. GRASS publishes to NATS subjects
3. Clients connect to NATS and subscribe to subjects

Documentation: protocols/streaming.md, api/streaming/event-schemas.md, api/streaming/event-types.md, api/streaming/subscription-patterns.md

Subject Patterns

// Subscribe example:
{
  "subject": "structs.player.0-1.1-11",
  "subject": "structs.planet.3-1"
}

// Message example:
{
  "subject": "structs.player.0-1.1-11",
  "category": "player_consensus",
  "id": "1-11",
  "updated_at": "2025-01-01T00:00:00Z",
  "data": {...}
}

NATS WebSocket (grass-nats-websocket)

• Method: WebSocket
• URL: ws://localhost:1443
• Authentication: Optional

NATS WebSocket wrapper for browser compatibility. Requires NATS server WebSocket support.

Supports the same subject patterns as the NATS protocol endpoint.

// Subscribe example:
{
  "action": "subscribe",
  "subjects": ["structs.player.0-1.1-11", "structs.planet.3-1"]
}

// Message example:
{
  "subject": "structs.player.0-1.1-11",
  "category": "player_consensus",
  "id": "1-11",
  "updated_at": "2025-01-01T00:00:00Z",
  "data": {...}
}

Related Documentation

• schemas/entities.md - Entity definitions
• schemas/actions.md - Action definitions
• schemas/responses.md - Response definitions
• reference/api-quick-reference.md - API quick reference
• api/streaming/event-types.md - Event type definitions
• api/streaming/subscription-patterns.md - Subscription patterns
• api/error-codes.md - Error code catalog
• api/rate-limits.md - Rate limit configuration