API Request Schemas

Version: 1.0.0 Category: api Schema: JSON Schema Draft-07 Description: Complete catalog of all API request body formats for AI agents. See schemas/formats.md for format specifications.

Request Type Index

Category Request Types
Authentication AuthSignupRequest, AuthLoginRequest
Player PlayerUsernameUpdateRequest, PlayerRaidSearchQuery, PlayerTransferSearchQuery
Player Address PlayerAddressAddPendingRequest, PlayerAddressMetaRequest, PlayerAddressActivationCodeRequest, PlayerAddressPendingPermissionsRequest, PlayerAddressPermissionsRequest
Transaction TransactionRequest
Query QueryParameters, PlayerRaidSearchQuery, PlayerTransferSearchQuery, GuildNameFilterQuery, GuildDirectoryQuery

Authentication Requests

AuthSignupRequest

Register a new player account.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address (e.g., cosmos1...)
signature string   Yes Signature for authentication
message string   Yes Message to sign

AuthLoginRequest

Authenticate and log in a player.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address
signature string   Yes Signature for authentication
message string   Yes Message to sign

Player Requests

Player Name and PFP Updates

Username and PFP are updated via the on-chain transactions MsgPlayerUpdateName, MsgPlayerUpdatePfp, and MsgPlayerUpdatePfpClientRenderAttributes (the composited 5-layer avatar recipe). Validation is enforced by the chain validators in ValidatePlayerName / ValidatePfp / ValidatePfpClientRenderAttributes – see schemas/validation.md#ugc-name-and-pfp-validation and knowledge/mechanics/ugc-moderation.md for the rules.

PlayerRaidSearchQuery

Query parameters for player raid search.

Field Type Format Required Description
player_id string entity-id No Player identifier in format type-index (e.g., 1-11). Pattern: ^1-[0-9]+$. Type 1 = Player.
status string   No Raid status filter. Values: active, completed, failed

PlayerTransferSearchQuery

Query parameters for player transfer search.

Field Type Format Required Description
player_id string entity-id No Player identifier in format type-index (e.g., 1-11). Pattern: ^1-[0-9]+$. Type 1 = Player.
from string date-time No Start date for search
to string date-time No End date for search

Player Address Requests

PlayerAddressAddPendingRequest

Add player pending address.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address to add
player_id string entity-id Yes Player identifier in format type-index (e.g., 1-11). Pattern: ^1-[0-9]+$. Type 1 = Player.

PlayerAddressMetaRequest

Add player address metadata.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address
meta object   Yes Metadata object (arbitrary key-value pairs)

PlayerAddressActivationCodeRequest

Create player address activation code.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address
player_id string entity-id Yes Player identifier in format type-index (e.g., 1-11). Pattern: ^1-[0-9]+$. Type 1 = Player.

PlayerAddressPendingPermissionsRequest

Set pending address permissions.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address
permissions array of string   Yes List of permissions

PlayerAddressPermissionsRequest

Set address permissions.

Field Type Format Required Description
address string blockchain-address Yes Blockchain address
permissions array of string   Yes List of permissions

Transaction Requests

TransactionRequest

Cosmos SDK transaction request. See schemas/actions.md for complete message type definitions.

Field Type Required Description
body object Yes Transaction body
auth_info object Yes Authentication information
signatures array of string Yes Transaction signatures (base64 encoded), minimum 1

body

Field Type Required Description
messages array of TransactionMessage Yes Array of transaction messages (minimum 1). See schemas/actions.md for complete message schemas.
memo string No Transaction memo
timeout_height string No Timeout height

auth_info

Field Type Required Description
signer_infos array Yes Signer information
fee object Yes Transaction fee

Each entry in signer_infos:

Field Type Description
public_key object Public key information
mode_info object Signing mode information
sequence string Account sequence number

The fee object:

Field Type Description
amount array Fee amount entries, each with denom (e.g., ustructs) and amount (as string)
gas_limit string Gas limit
payer string (blockchain-address) Fee payer address (optional)
granter string (blockchain-address) Fee granter address (optional)

TransactionMessage

Base transaction message structure. All messages must include @type. See schemas/actions.md for specific message schemas.

Each message type has specific required fields beyond what is listed here.

Field Type Required Description
@type string Yes Message type URL (see below)
creator string (blockchain-address) Varies Transaction creator address (required for most messages)

Available Message Types

The @type field must be one of the following message types:

Message Type Description
/structs.structs.MsgStructBuild Build a struct
/structs.structs.MsgStructBuildInitiate Initiate struct build
/structs.structs.MsgStructBuildComplete Complete struct build
/structs.structs.MsgStructActivate Activate a struct
/structs.structs.MsgStructDeactivate Deactivate a struct
/structs.structs.MsgStructDeactivateBatch Deactivate up to 65 structs in one transaction (structId is a list)
/structs.structs.MsgStructTrash Permanently destroy a built struct (costs buildCharge, irreversible)
/structs.structs.MsgStructStealthActivate Stealth activate a struct
/structs.structs.MsgStructStealthDeactivate Stealth deactivate a struct
/structs.structs.MsgStructAttack Attack with a struct
/structs.structs.MsgStructDefenseSet Set struct defense
/structs.structs.MsgStructDefenseClear Clear struct defense
/structs.structs.MsgStructMove Move a struct
/structs.structs.MsgStructOreMinerComplete Complete ore mining
/structs.structs.MsgStructOreRefineryComplete Complete ore refining
/structs.structs.MsgPlanetExplore Explore a planet (optional name field)
/structs.structs.MsgGuildUpdatePrimaryReactor Reassign guild primary reactor
/structs.structs.MsgPlanetRaidComplete Complete a planet raid
/structs.structs.MsgFleetMove Move a fleet
/structs.structs.MsgReactorInfuse Infuse a reactor
/structs.structs.MsgReactorDefuse Defuse a reactor
/structs.structs.MsgStructGeneratorInfuse Infuse a generator with Alpha Matter
/structs.structs.MsgSubstationCreate Create a substation
/structs.structs.MsgSubstationPlayerConnect Connect player to substation
/structs.structs.MsgSubstationAllocationConnect Connect an allocation to a substation
/structs.structs.MsgAllocationCreate Create an allocation from a source object (creator, controller, sourceObjectId, allocationType, power)
/structs.structs.MsgAllocationUpdate Update a dynamic allocation’s power (creator, allocationId, power)
/structs.structs.MsgAllocationDelete Delete an allocation (creator, allocationId)
/structs.structs.MsgAllocationTransfer Reassign an allocation’s controller (creator, allocationId, controller)
/structs.structs.MsgProviderCreate Create a provider
/structs.structs.MsgAgreementOpen Open an energy agreement
/structs.structs.MsgGuildCreate Create a guild
/structs.structs.MsgGuildMembershipJoin Join a guild
/structs.structs.MsgGuildMembershipKick Remove a member from a guild
/structs.structs.MsgGuildBankMint Mint from guild bank
/structs.structs.MsgGuildBankRedeem Redeem from guild bank

Query Parameters

QueryParameters

Common query parameters for list endpoints.

Field Type Default Constraints Description
pagination.key string     Pagination key for next page
pagination.limit integer 50 min: 1, max: 100 Number of items per page
pagination.offset integer   min: 0 Number of items to skip

GuildNameFilterQuery

Query parameters for guild name filter.

Field Type Required Description
filter string No Name filter string

GuildDirectoryQuery

Query parameters for guild directory.

Field Type Default Constraints Description
page integer 1 min: 1 Page number
limit integer 20 min: 1, max: 100 Items per page