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
}
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
}
}
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
andrandValue
, along with other details, are used as parameters when calling thecreateAttestation
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)
}
}
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"
}
}
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"
}
}
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
andrandValue
are used as parameters when calling thecreateSlash
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 validattestationDetails
.The signature combines the authenticated user's profile ID, a random value, and all slash parameters.
Last updated