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.
1

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
  • 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:
{
    "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:
{
    "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).
2

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
  • 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:
{
    "status": "PENDING"
}
  • Success:
{
    "status": "DONE",
    "signature": "0x1234567890abcdef..."
}
  • Failure:
{
    "status": "FAILED",
    "error": "Signing failed due to..."
}
  • 404 Not Found: Returned if the request-id is not found.
{
    "error": "Request not found"
}