Signatures

Overview

The Signatures API provides endpoints for generating backend signatures required for certain blockchain transactions within the Ethos network. These signatures authorize actions like creating attestations, registering addresses, or submitting slashes, ensuring that only authenticated and validated operations proceed to the smart contracts.

Endpoints

Create Attestation Signature

POST /api/v1/signatures/create-attestation

Description: Creates a backend-generated signature required for submitting an attestation transaction (e.g., linking a Twitter account) to the blockchain.

Authentication Required: Yes (Requires Privy Session and Profile)

Parameters

Request Body

{
  "service": "x.com", // Currently only "x.com" is supported
  "connectedAddress": "string" // Wallet address connected via Privy
}
Property
Type
Required
Description

service

string

Yes

The service name being attested (currently must be x.com).

connectedAddress

string

Yes

The wallet address connected via Privy, matching the session.

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "randValue": number,   // Random nonce value used in the signature
    "signature": "string", // The backend-generated signature (hex string)
    "account": "string",   // The account ID retrieved from the user's linked Privy account (e.g., Twitter ID)
    "evidence": "string"  // JSON string containing evidence details used in the signature
  }
}
Property
Type
Description

ok

boolean

Indicates if the API call itself was successful.

data

object

Container for the response data.

data.randValue

number

A random nonce value (timestamp) included in the signed message.

data.signature

string

The signature generated by the backend signer over the attestation details.

data.account

string

The account identifier (e.g., Twitter User ID) retrieved from the user's linked Privy account.

data.evidence

string

A JSON string containing details about the attestation source (Privy OAuth2).

Error Responses

Code: 400 Bad Request

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR | BAD_REQUEST",
    "message": "Invalid service/connectedAddress | Social account already connected"
  }
}

Code: 401 Unauthorized

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED", // Middleware handles missing token
    "message": "Authentication required"
  }
}

Code: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Invalid Privy session | No Twitter account connected"
  }
}

Example

Request

# Needs auth token and connected wallet address
CONNECTED_WALLET="0x123...abc"
http POST https://api.ethos.network/api/v1/signatures/create-attestation \
  Authorization:"Bearer <AUTH_TOKEN>" \
  service=x.com \
  connectedAddress=$CONNECTED_WALLET

Response

{
  "ok": true,
  "data": {
    "randValue": 1678982400123,
    "signature": "0x8a7bc52fd7164a3f12b49b6c5f68c6f69de31f515e4d4ec7c055686c8de6331a4b5e09be6e38b9d30b25f3f178c34c7d82778f1c2c6f3dfd0e25e1474a3e83b41c",
    "account": "1234567890",
    "evidence": "{\"source\":\"privy\",\"type\":\"OAuth2\",\"id\":\"did:privy:abc123def456\",\"approver\":\"ethos.network\"}"
  }
}

Notes

  • Requires authentication.

  • The user must have linked the specified service (Twitter) to their Privy account beforehand.

  • Checks if the connectedAddress matches the authenticated user's Privy session.

  • Verifies that an attestation doesn't already exist for this profile/service/account.

  • The returned signature and randValue, along with other details, are used as parameters when calling the createAttestation function on the Ethos Attestation smart contract.

Create Register Address Signature

POST /api/v1/signatures/register-address

Description: Creates a backend-generated signature required for submitting a transaction to register the authenticated user's smart wallet address with their profile on the blockchain.

Authentication Required: Yes (Requires Privy Session and Profile)

Parameters

None (The address to register is the smartWallet derived from the authenticated user's Privy session).

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "randValue": number,   // Random nonce value used in the signature
    "signature": "string" // The backend-generated signature (hex string)
  }
}
Property
Type
Description

ok

boolean

Indicates if the API call itself was successful.

data

object

Container for the response data.

data.randValue

number

A random nonce value (timestamp) included in the signed message.

data.signature

string

The signature generated by the backend signer over the registration details (profileId, address, randValue).

Error Responses

Code: 400 Bad Request

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Wallet already connected to the profile"
  }
}

Code: 401 Unauthorized

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED", // Middleware handles missing token
    "message": "Authentication required"
  }
}

Code: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN | NO_ETHOS_PROFILE",
    "message": "Invalid Privy session | No Ethos profile linked" // Service combines these under Forbidden
  }
}

Example

Request

# Needs auth token
http POST https://api.ethos.network/api/v1/signatures/register-address \
  Authorization:"Bearer <AUTH_TOKEN>"

Response

{
  "ok": true,
  "data": {
    "randValue": 1678982401234,
    "signature": "0x5c2f45e93d0ae7776e7347fc6a22b851c5f26b7c6d17a7ff14c8982e5729d41971dc8e3a7a27f06c383ad7a64981a81c2ba0391a833a24cd8a176abfe333a8cc1b"
  }
}

Notes

  • Requires authentication.

  • Retrieves the user's smartWallet address from their Privy session.

  • Checks that the smart wallet isn't already registered to the profile.

  • Creates a signature that the user needs to use when calling the registerAddress function on the Ethos Profile smart contract.

  • This signature proves the backend authorizes the registration of the user's smart wallet to their profile ID.

Create Slash Signature

POST /api/v1/signatures/create-slash

Description: Creates a backend-generated signature required for submitting a slash transaction to the blockchain. A slash is a community moderation action that can affect a user's score or financial status.

Authentication Required: Yes (Requires Privy Session and Profile)

Parameters

Request Body

{
  "subject": "0x1234...5678", // Can be null if using attestationDetails
  "amount": 100,
  "comment": "Reason for slash",
  "metadata": "{\"description\":\"Additional details about the slash\"}",
  "attestationDetails": {
    "service": "x.com",
    "account": "1234567890"
  }
}
Property
Type
Required
Description

subject

string

No*

Ethereum address of the subject being slashed (null if using attestation).

amount

number

Yes

Positive integer representing the severity/amount of the slash.

comment

string

Yes

Description of why the slash was created (min length 1).

metadata

string

Yes

JSON string with additional metadata about the slash.

attestationDetails

object

Yes

Details about the attestation if slashing by service/account.

attestationDetails.service

string

Yes

Service name (e.g., "x.com").

attestationDetails.account

string

Yes

Account identifier for the service.

*Either subject (for address-based slashes) or valid attestationDetails (for attestation-based slashes) must be provided.

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "randValue": 1678982401234,
    "signature": "0x123456...abcdef"
  }
}
Property
Type
Description

ok

boolean

Indicates if the API call itself was successful.

data

object

Container for the response data.

data.randValue

number

A random nonce value (timestamp) included in the signed message.

data.signature

string

The signature generated by the backend signer over the slash details.

Error Responses

Code: 400 Bad Request

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters"
  }
}

Code: 401 Unauthorized

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Code: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Invalid Privy session | User cannot slash",
    "details": {
      "code": "FORBIDDEN_SLASH"
    }
  }
}

Example

Request

# Needs auth token
http POST https://api.ethos.network/api/v1/signatures/create-slash \
  Authorization:"Bearer <AUTH_TOKEN>" \
  subject=null \
  amount:=100 \
  comment="Impersonating other users" \
  metadata="{\"description\":\"Created fake account mimicking project founder\"}" \
  attestationDetails:='{"service":"x.com","account":"1234567890"}'

Response

{
  "ok": true,
  "data": {
    "randValue": 1678982401234,
    "signature": "0x4d8fb7c124fecb927e35b7dc913b2716f5ce9c7bb6075cbde0bd41677c095c6b5cdcce7f2605a6161a86202feea8a9b6aa051b0d9c995a79a42e71551dc23cf31b"
  }
}

Notes

  • Requires authentication.

  • The user must have permission to create slashes (authorization checked by the canSlash function).

  • The returned signature and randValue are used as parameters when calling the createSlash function on the Ethos Slash smart contract.

  • For address-based slashes, provide the subject parameter with an Ethereum address.

  • For attestation-based slashes (e.g., Twitter accounts), set subject to null and provide valid attestationDetails.

  • The signature combines the authenticated user's profile ID, a random value, and all slash parameters.

PreviousSearchNextSlashes

Last updated