Sign Resource Overview

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

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"
}