> ## Documentation Index > Fetch the complete documentation index at: https://shield.fi/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get protocol state > Get a revisioned snapshot of protocol controls and routing configuration. ## OpenAPI ````yaml openapi.json GET /protocol/state openapi: 3.1.0 info: title: Shield Swap API description: >- Shield Swap REST API for pools, positions, swaps, routes, quotes, settlement status, and transaction input schemas. Transactions target the configured shield_swap program and `token_registry.aleo`. ## Numeric wire format Exact financial values are JSON strings, not JSON numbers. Unsigned decimal inputs use ASCII digits and an optional `.` fraction, for example `"1234.50"`; base-unit integers use ASCII digits only. Grouping separators, localized decimal commas, signs, exponent notation, whitespace, Unicode digits, and redundant leading zeros are not accepted for those inputs. Signed response metrics may include a leading `-`. Clients should localize only for display and convert user input back to this canonical form before sending it. ## Authentication Most endpoints require credentials from an invited wallet. Public routes are `/health`, `/ready`, `/metrics`, `/auth/*`, `/protocol/state`, `/compliance*`, `GET /tokens*`, `GET /pools`, `GET /pools/stats`, and `GET /pools/{key}`. Browsers use HTTP-only session cookies issued by `/auth/verify`. Access sessions last 15 minutes and are renewed through `/auth/refresh`. Programmatic clients use a long-lived token from `POST /api-tokens` as `Authorization: Bearer ss_…`. API tokens cover data and trading routes and can request WebSocket tickets. Token management, code redemption, and admin routes require a browser session. ## WebSocket feed The live feed runs on the separate websocket gateway at `GET /ws`. 1. Request a ticket from `GET /auth/ws-ticket` using a browser session or API token. 2. Open the socket and send the `authenticate` frame within 5 seconds. 3. Subscribe to each required room. 4. Before the 60-second ticket expires, request a new ticket and send another `authenticate` frame. The socket accepts WebSocket tickets only. Session JWTs and API tokens are rejected. ```json {"action": "authenticate", "token": ""} {"action": "subscribe", "room": "trades:"} {"action": "unsubscribe", "room": ""} {"action": "synchronize"} ``` After reconnecting, resend subscriptions and then send `synchronize`. The gateway replies `{"control": "synchronized"}` when those subscriptions are active. Refetch any REST data that depends on the stream after receiving the reply. Each connection allows 32 rooms, 240 client frames per minute, and 2 KB per frame. A client may subscribe only to the balance room for its ticket subject. Rooms: - `pool_launches`: newly created pools - `pool_stats:`: price & liquidity updates - `ohlcv:`: candle updates - `trades:`: swaps / mints / burns - `balances:
`: balance-change hints for an address - `protocol_config`: revisioned protocol-configuration invalidations Server messages are either events (`{"type": , "data": { … }}`) or control messages (`{"control": }`). Event types are `PoolLaunch`, `PoolStats`, `Ohlcv`, `Trade`, `BalanceChange`, and `ProtocolConfigChanged`. Its data contains `revision`, `observed_block`, and the changed `scope`/`key` pairs. Financial fields use the numeric format described above. Treat `ProtocolConfigChanged` as an invalidation, not as the new configuration. Fetch `GET /protocol/state?minimum_revision=`; retry a `503 protocol_revision_pending` after the advertised `Retry-After`; and discard or requote any `/route` result whose `protocol_revision` is older. Subscribe to `pool_stats:` separately when live price and liquidity updates matter. The gateway currently sends `synchronized` and `resync_required` controls. `resync_required` means the stream may have missed updates, so refetch affected data over REST. Ignore unknown control values. Event delivery is at most once. Treat REST as the source of truth. During a deployment the gateway may close the socket with code 1012 (service restart); reconnect and restore the subscriptions. contact: name: Shield Swap license: name: '' version: 0.1.0 servers: - url: https://api.swap.shield.fi description: Shield Swap mainnet API security: [] tags: - name: schema description: On-chain function input schemas for trading / liquidity / token operations - name: auth description: Wallet sign-in, sessions, logout, and WebSocket tickets - name: access description: Invite access redemption and administration - name: api-tokens description: >- Long-lived API tokens for programmatic access; send as `Authorization: Bearer ss_…` on any gated endpoint - name: referral description: Referral redemption and administration - name: pools description: Pool metadata, stats, trades, OHLCV - name: positions description: LP positions - name: swaps description: Historical swaps - name: tokens description: Token registry - name: balances description: On-chain token balances - name: compliance description: Token/pair allowlist, pause, and pool-creation gating state - name: protocol description: Fee tiers and tick spacings - name: route description: Swap routing - name: debug description: On-chain introspection helpers - name: airdrop description: >- Faucet: sends ALEO, USDCx, and ETH to a user address as records, once per address per 15 min - name: unclaimed description: Pending swap outputs and position fees paths: /protocol/state: get: tags: - protocol summary: Get protocol state operationId: get_protocol_state parameters: - name: minimum_revision in: path required: true schema: type: - integer - 'null' format: int64 responses: '200': description: Canonical versioned protocol state content: application/json: schema: $ref: '#/components/schemas/ProtocolStateResponse' '304': description: Protocol state matches If-None-Match '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDoc' '503': description: The requested protocol revision has not been indexed content: application/json: schema: $ref: '#/components/schemas/ProtocolRevisionPending' components: schemas: ProtocolStateResponse: type: object required: - revision - freshness - live_compatibility - deployment - controls - fee_configuration - capabilities properties: capabilities: $ref: '#/components/schemas/ProtocolCapabilities' changed_at: type: - string - 'null' format: date-time controls: $ref: '#/components/schemas/ProtocolControls' deployment: $ref: '#/components/schemas/ProtocolDeployment' fee_configuration: $ref: '#/components/schemas/ProtocolFeeConfiguration' freshness: $ref: '#/components/schemas/ProtocolFreshness' live_compatibility: $ref: '#/components/schemas/LiveCompatibility' observed_block: type: - integer - 'null' format: int64 revision: type: integer format: int64 ErrorResponseDoc: type: object required: - error properties: error: type: string ref: type: - string - 'null' ProtocolRevisionPending: type: object required: - error - code - minimum_revision - current_revision properties: code: type: string current_revision: type: integer format: int64 error: type: string minimum_revision: type: integer format: int64 ProtocolCapabilities: type: object required: - faucet - token_admin - debug_api - freezelist_proofs - protocol_config_websocket properties: debug_api: type: boolean faucet: type: boolean freezelist_proofs: type: string protocol_config_websocket: type: boolean token_admin: type: boolean ProtocolControls: type: object required: - global_paused - pool_creation_is_open - allowed_tokens - paused_tokens - paused_pairs - disabled_pools properties: allowed_tokens: type: array items: type: string disabled_pools: type: array items: type: string global_paused: type: boolean paused_pairs: type: array items: $ref: '#/components/schemas/ProtocolPair' paused_tokens: type: array items: type: string pool_creation_is_open: type: boolean ProtocolDeployment: type: object required: - profile - network - verified_at - amm_start_block - contract_repository - contract_ref - protocol_version - abi_version - math_version - freezelist_proof_version - deployment_fingerprint - programs properties: abi_version: type: integer format: int32 minimum: 0 amm_start_block: type: integer format: int64 minimum: 0 contract_ref: type: string contract_repository: type: string deployment_fingerprint: type: string freezelist_proof_version: type: string math_version: type: string network: type: string profile: type: string programs: type: object additionalProperties: $ref: '#/components/schemas/ProtocolProgram' propertyNames: type: string protocol_version: type: integer format: int32 minimum: 0 verified_at: type: string ProtocolFeeConfiguration: type: object required: - registered_fee_tiers - registered_tick_spacings - valid_bindings - pool_fee_protocols properties: pool_fee_protocols: type: array items: $ref: '#/components/schemas/PoolFeeProtocol' registered_fee_tiers: type: array items: type: integer format: int32 registered_tick_spacings: type: array items: type: integer format: int32 valid_bindings: type: array items: $ref: '#/components/schemas/FeeBinding' ProtocolFreshness: type: object required: - ready_for_entry properties: confirmed_head: type: - integer - 'null' format: int64 indexed_block: type: - integer - 'null' format: int64 lag_blocks: type: - integer - 'null' format: int64 ready_for_entry: type: boolean updated_at: type: - string - 'null' format: date-time LiveCompatibility: type: object required: - status - checked_at - artifacts_checked - failures properties: artifacts_checked: type: integer minimum: 0 checked_at: type: string format: date-time failures: type: array items: $ref: '#/components/schemas/LiveCompatibilityFailure' status: $ref: '#/components/schemas/LiveCompatibilityStatus' ProtocolPair: type: object required: - token0 - token1 properties: token0: type: string token1: type: string ProtocolProgram: type: object required: - program_id - role - source_sha256 properties: edition: type: - integer - 'null' format: int32 minimum: 0 program_id: type: string role: type: string source_sha256: type: string PoolFeeProtocol: type: object required: - pool_key - fee_protocol properties: fee_protocol: type: integer format: int32 pool_key: type: string FeeBinding: type: object required: - fee_tier - tick_spacing properties: fee_tier: type: integer format: int32 tick_spacing: type: integer format: int32 LiveCompatibilityFailure: type: object required: - code properties: code: $ref: '#/components/schemas/LiveCompatibilityFailureCode' program_id: type: - string - 'null' LiveCompatibilityStatus: type: string enum: - compatible - incompatible - unavailable LiveCompatibilityFailureCode: type: string enum: - cache_unavailable - edition_mismatch - edition_unavailable - rate_limited - rpc_unavailable - source_mismatch - source_unavailable - verification_timeout ````