Skip to main content

Relay HTTP API

The Relay HTTP API provides a RESTful interface for interacting with the Symbiotic Relay system. The API enables signature aggregation, validator set queries, and network status monitoring.

Request/response formats​

All requests and responses use JSON format with application/json content type. Binary data is encoded as base64 strings.

Error Response Format​

{
    "errorMessage": "User-friendly error description",
    "errorCode": "noData|oops|notAnAggregator"
}

Error Codes:

  • noData - Requested data not found
  • notAnAggregator - Operation only available on aggregator nodes

Network Status endpoints​

GET /getCurrentEpoch​

Returns the current epoch number and start time.

Response:

{
    "epoch": 12345,
    "startTime": "2023-01-01T00:00:00Z"
}

GET /getSuggestedEpoch​

Returns the suggested epoch for signing requests.

Response:

{
    "epoch": 12345,
    "startTime": "2023-01-01T00:00:00Z"
}

GET /getValidatorSet?epoch={epochNumber}​

Returns validator set for specified epoch (current epoch if not provided).

Parameters:

  • epoch (optional) - Epoch number (uint64)

Signer Operations​

POST /signMessage​

Initiates message signing with specified parameters.

Request Body:

{
    "keyTag": 1,
    "message": "<base64-encoded-message>",
    "requiredEpoch": 12345
}

Parameters:

  • keyTag (required) - Cryptographic key identifier (uint8)
  • message (required) - Message to sign (base64 encoded bytes)
  • requiredEpoch (optional) - Target epoch for signing (uint64)

Response:

{
    "requestHash": "unique-request-identifier",
    "epoch": 12345
}

GET /getAggregationProof?requestHash={hash}​

Retrieves aggregation proof for a completed signature request.

Parameters:

  • requestHash (required) - Request identifier from signMessage response

GET /getAggregationStatus?requestHash={hash}​

Note: Aggregator nodes only

Returns current aggregation progress for a signature request.

Parameters:

  • requestHash (required) - Request identifier

Response:

{
    "currentVotingPower": "1000000000000000000",
    "signerOperators": ["0x123...", "0x456..."]
}

GET /getSignatures?requestHash={hash}​

Returns individual signatures collected for a request.

Parameters:

  • requestHash (required) - Request identifier

GET /getSignatureRequest?requestHash={hash}​

Returns the original signature request details.

Parameters:

  • requestHash (required) - Request identifier

Data Models​

SignatureRequest​

{
    "keyTag": 1,
    "message": "base64-encoded-message",
    "requiredEpoch": 12345
}

AggregationProof​

{
    "verificationType": 1,
    "messageHash": "base64-encoded-hash",
    "proof": "base64-encoded-proof"
}

ValidatorSet​

{
  "version": 1,
  "requiredKeyTag": 1,
  "epoch": 12345,
  "captureTimestamp": "2023-01-01T00:00:00Z",
  "quorumThreshold": "66",
  "previousHeaderHash": "0x...",
  "status": 0,
  "validators": [...]
}

Status Values:

  • 0 - Pending
  • 1 - Missed
  • 2 - Committed

Validator​

{
  "operator": "0x123...",
  "votingPower": "1000000000000000000",
  "isActive": true,
  "keys": [...],
  "vaults": [...]
}

Signature​

{
    "signature": "base64-encoded-signature",
    "messageHash": "base64-encoded-hash",
    "publicKey": "base64-encoded-key"
}