> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecrop.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign Resource Overview

> Understanding message signing within the OmniSafe API.

This document explains how to request and retrieve the status of message signatures using the OmniSafe API.  The signing process leverages private keys securely stored within our custody system and requires approval via our Proof of Action (PoA) mechanism.

<Steps>
  <Step title="Requesting a Message Signature">
    To request a signature for an Ethereum message, use the `POST /v1/signs` endpoint.  This process is asynchronous and requires approval through our Proof of Action (PoA) mechanism.

    * **Endpoint:** `POST /v1/signs` - [Request Signature API Reference](/omni-platform/omniomni-components/omni-safe/signs-post)
    * **Summary:** Request message signing (custody-based with callback).
    * **Description:** Submits a request to sign an Ethereum message using private keys securely stored within the OmniSafe custody system.

    **Request Body:**

    The request body should be a JSON object with the following properties:

    * `message` (string, required): The message to be signed, Base64 encoded. Example: `"SGVsbG8gV29ybGQh"` (which decodes to "Hello World!").
    * `address` (string, required): The user's wallet address. Example: `"0x..."`
    * `callbackUrl` (string, required): URL to receive the signing result via webhook. Example: `"https://example.com/callback"`
    * `chainId` (integer, required, Ethereum Specific): Ethereum chain ID (EIP-155). Example: `1`

    **Response:**

    * `202 Accepted`: Signing request accepted.  Returns a JSON object with the `requestId`:

    ```json theme={null}
    {
        "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    }
    ```

    * `400 Bad Request`:  Returned for invalid requests (e.g., missing parameters, invalid address, invalid Base64 message). The response includes an error message. Example:

    ```json theme={null}
    {
        "error": "Invalid address"
    }
    ```

    **Important Considerations:**

    * **Asynchronous Signing:**  The signing process is *asynchronous*. After submitting the request, you will receive a `requestId`. You *must* use the `requestId` to check the signing status.  You will also receive the signing result via the specified `callbackUrl`.
    * **Proof of Action (PoA):** Signing requires approval from the wallet owner(s) through our PoA mechanism. This approval process is initiated after the request is submitted.
    * **Base64 Encoding:** The `message` field *must* be Base64 encoded.
    * **Callback URL:** Ensure your `callbackUrl` is properly configured to receive the signing result (signature or error).
  </Step>

  <Step title="Getting Signing Request Status">
    To retrieve the status of a specific signing request, use the `GET /v1/signs/{request-id}` endpoint.

    * **Endpoint:** `GET /v1/signs/{request-id}` - [Get Signature Status API Reference](/omni-platform/omniomni-components/omni-safe/signs-get)
    * **Summary:** Gets the status of a specific signing request.
    * **Description:** Retrieves the status of a specific signing request. Returns the signing status (PENDING, DONE, or FAILED). If DONE, includes the generated signature.

    **Parameters:**

    * `request-id` (path parameter, required): The ID of the signing request, obtained from the `POST /v1/signs` response.

    **Response:**

    * `200 OK`: Returns a JSON object with the signing status.  The response includes:
    * `status` (string): The signing status (either `"PENDING"`, `"DONE"`, or `"FAILED"`).
    * `signature` (string, optional): The signature (hexadecimal), only present if `status` is `"DONE"`. Example: `"0x..."`
    * `error` (string, optional): An error message, only present if `status` is `"FAILED"`. Example: `"Signing failed"`

    Examples:

    * Pending:

    ```json theme={null}
    {
        "status": "PENDING"
    }
    ```

    * Success:

    ```json theme={null}
    {
        "status": "DONE",
        "signature": "0x1234567890abcdef..."
    }
    ```

    * Failure:

    ```json theme={null}
    {
        "status": "FAILED",
        "error": "Signing failed due to..."
    }
    ```

    * `404 Not Found`: Returned if the `request-id` is not found.

    ```json theme={null}
    {
        "error": "Request not found"
    }
    ```
  </Step>
</Steps>