Sign

The Sign endpoint allows you to create a digital signature for a transaction payload. This signature is generated using keys stored securely in the Signchain Vault, ensuring the transaction's integrity and security.

Endpoint

POST/api/v1/vaults/:vaultId/sign

Test Endpoint

Request Headers

Authorization: Bearer token for authentication. Should be Bearer <Your-API-Key>.
X-Vault-Auth-Signature: Required only when VAULT_AUTH_SECRET_KEY has been configured on a self-hosted vault, for securing the request with a unique signature, generated with the shared secret. Inclusion of this parameter guarantees security of your vault's private key data, by disallowing requests unless the signature is valid and matches the shared key between your backend and your self-hosted vault instance. If you're using the Signchain Hosted Vault, this parameter must not be included, otherwise the signing request will fail.
Content-Type: Must be application/json.
Accept: Must be application/json.

Request Parameters

vaultId: The unique identifier of your Signchain Vault.

Request Body

The request body must include the transaction data to be signed:

{
  "chain": "<Your-Contracts-Chain>",
  "contract": "<Your-Contract-Address>",
  "sender": "<Your-Users-Address>",
  "uniq": "<Your-Optional-Contracts-Uniq-Value>",
  "signer": "<Your-Optional-Contracts-Signer-Value>",
  "abi": {
    ...Your_Contract_Function_ABI_Item
  },
  "args": [
    ...Your_Contract_Function_Arguments
  ]
}

Required Field

chain: The chain which the contract exists on, should be one of the supported chains ethereum, sepolia, bsc, bsc-testnet, polygon, amoy, avalanche, fuji. If you are developing locally, use local and ensure you submit the ISignable contract's uniq and signer values.
contract: The deployed contract address from where Signchain can lookup uniq and signer values.
sender: The user's wallet address from where the transaction will be sent from.
uniq: (Optional) The bytes32 uniq value from the deployed contract. This is required for local development, or for chains which are not supported, and where Signchain can't lookup the value automatically.
signer: (Optional) The address signer value from the deployed contract. This is required for local development, or for chains which are not supported, and where Signchain can't lookup the value automatically.
abi: The ABI Item description for the method you are signing for. An ABI is an array of ABI Items, make sure you filter the ABI to just select the ABI Item related to your contact method. The client libraries do this selection automatically based on the functionName argument to sign.
args: The contract function's arguments as an array, excluding the last signature parameter.

Response

On success, the API returns the transaction signature:

{
  "success": Request_Success_Status,
  "data": {
    "submissionHash": "<Your-Sign-Request-Submission-Hash>",
    "args": [
      ...Your_Supplied_Arguments,
      {
        ...Nonce_R_S_V_Signature_Struct
      }
    ]
  },
  "error": "<Request-Error-Message>"
}

Response Fields

success: A boolean true or false determining whether the sign request was successful or not. If the sign request was not successful, this value will be false and the error field will be populated.
error: A string error message, only sent if the success parameter is false.
data: The response data for the request, only sent if the success parameter is true.
submissionHash: The unique identifier for this sign response, allowing you to correlate the transaction data on Signchain's Dashboard with a blockchain specific transaction hash, after the transaction has been submitted by the user. Supply this value to the submit endpoint once the transaction has been executed.
args: A full list of arguments which you supplied in the request that can be sent on-chain, with the signature argument appended to the list. These arguments should be provided back to the user in their entirety in order to execute the transaction.

Example Request

Here's an example of how to sign a transaction using curl:

curl -X POST https://signchain.net/api/v1/vaults/:vaultId/sign \
     -H "Authorization: Bearer <Your-API-Key>" \
     -H "Content-Type: application/json" \
     --data-binary @- <<EOF
{
  "chain": "<Your-Contracts-Chain>",
  "contract": "<Your-Contract-Address>",
  "sender": "<Your-Users-Address>",
  "abi": $(cat MyContractABI.json | jq '.[] | select(.name == "<Your-Function-Name>")'),
  "args": [...<Your-Function-Arguments>]
}
EOF

Error Handling

This endpoint can return the following errors:

400 Bad Request: Missing or invalid transaction data.
401 Unauthorized: Incorrect API key or X-Vault-Auth-Signature.
404 Not Found: The specified vault or wallet address does not exist.
500 Internal Server Error: An unexpected error occurred while processing the request.

Refer to the Authentication documentation to ensure proper setup of your API keys and request signatures.

This endpoint is critical for secure transaction processing, ensuring only authorized parties can initiate cryptographic operations using your self-hosted Signchain Vault.

Signchain Docs