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.

---