Blockchain signature flow

API endpoints that require the signing of a blockchain transaction cannot execute the transaction autonomously. Doing so would involve possession or access to the end-user’s private key, which poses a critical security risk.

To ensure secure handling of blockchain transactions, we provide three distinct integration flows. Each is tied to a different API endpoint or mechanism, depending on how you choose to sign and emit blockchain transactions.

For more information regarding the endpoints inputs/outputs: Swagger UI

 Option 1 - When to Use /transactions

Use this endpoint when your system signs and broadcasts the transaction directly to the blockchain.

This is ideal for apps that:

• Already manage their own transaction emission.
• Use your own backend infrastructure to manage signing and emission directly, or user-managed wallets like MetaMask for full control.

Process:

• Call the relevant Tokeny API to retrieve the unsigned transaction payload.
• Sign the received transactionData in your app (frontend or backend).
• Emit (broadcast) the transaction to the blockchain yourself.
• Call POST /transactions with the resulting txHash to log the transaction in our system. Once received, we will verify the transaction and update the off-chain data to reflect the on-chain state.

You may use any library - for example with ethers sendTransaction, which signs and broadcast it returning the txHash.

Frontend Signing Flow:

• Fetch payload → prompt user wallet to sign → broadcast via the used wallet → send txHash via /transactions.

Backend Signing Flow:

• Fetch payload → sign with backend wallet → broadcast using a provider → send txHash via /transactions.

 Option 2 - When to Use /payloads

Use this endpoint when your system signs the transaction but prefers Tokeny’s backend to handle broadcasting.

Best suited for:

• Integrators who want to avoid running blockchain nodes or using emit APIs.
• Systems that want partial control (signing only).

Process:

• Call the relevant Tokeny API to get the unsigned payload.
• Sign the received transactionData in your app (frontend or backend).
• Send the signed payload to POST /payloads.
• Our system will emit the transaction to the blockchain on your behalf, update the off-chain data to reflect the on-chain one and return the resulting txHash.

You may use any library, for example with ethers signTransaction, which sign and returns the signed data.

Frontend Signing Flow:

• Fetch payload → prompt user wallet to sign → send signed payload to /payloads.

Backend Signing Flow:

• Fetch payload → sign using backend wallet → send signed payload to /payloads.

Tokeny offers an Integrated Non-Custodial Wallet solution designed to remove the complexity of handling blockchain signatures and transaction emission for integrators.

This approach is fully managed on the Tokeny infrastructure side and eliminates the need for investors to manually sign transactions. It is ideal for use cases where convenience, security, and automation are required, without compromising control of private keys.

Process:

• Call the relevant Tokeny API to get the unsigned payload.
• Sign the received transactionData in your app (frontend or backend).
• If the involved investor uses an integrated wallet, Tokeny will automatically emits it to the blockchain

 Option 3 - When to Use Webhook Subscription

Use this approach when you want us to forward all transaction payloads to your wallet provider (only agents and owners accounts).

Ideal for:

• Teams that use custodial wallet services.
• Scenarios where security policy restricts key handling in-app.

Process:

• You subscribe to a webhook for a given wallet once and then:
• You initiate an action via a T-REX Engine API (e.g., minting tokens) which returns 201 Created, confirming the transaction is being prepared.
• Once the transaction is validated and payload is created, your configured webhook receives a POST request containing:
  • payload: The unsigned transaction to be signed.
  • workflowId: Internal ID for tracking and reconciliation.
• Your endpoint needs to sign the payload and to make a call to /payloads to broadcast it.

Benefits:

• No signing logic needed in your app, all is handled by the webhook.
• Great for Fireblocks (which uses MPC cryptography) or similar solutions.