# 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**

```json
{
  "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

```json
{
  "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

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

**Code**: 401 Unauthorized

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

**Code**: 403 Forbidden

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

#### Example

**Request**

```bash
# 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**

```json
{
  "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 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**

```json
{
  "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

```json
{
  "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

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

**Code**: 401 Unauthorized

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

**Code**: 403 Forbidden

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

#### Example

**Request**

```bash
# 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**

```json
{
  "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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.ethos.network/api-documentation/api-v1-deprecated/signatures.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.