Get Started with Finrock: Wallets and Transactions

This guide walks you through every step required to go from zero to a fully functioning integration with the Finrock API. By the end, you will have generated your credentials, created an MPC wallet, produced a deposit address, and submitted your first transaction — all using authenticated REST API calls against https://api.finrock.io.

Generate Your RSA Key Pair

Finrock authenticates API requests using JWT tokens signed with your RSA-4096 private key. You share the public key with Finrock; your private key never leaves your infrastructure.Run the following commands to generate a 4096-bit RSA key pair:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out private_key.pem
openssl pkey -in private_key.pem -pubout -out public_key.pem

This produces two files:

private_key.pem — your signing key; store this securely and never commit it to source control
public_key.pem — the key you upload to Finrock in the next step

Keep private_key.pem secret. Anyone who obtains your private key can sign API requests on your behalf. Store it in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) and restrict filesystem access to the process that needs it.

Get Your API Key

Upload the contents of public_key.pem when prompted for your RSA public key.
Copy the API Key UUID that is generated — it looks like 4466c45a-7b28-4c50-a0f7-198f8d7f34c5.

You will need this UUID as both the sub field in your JWT payload and as the value of the x-api-key header on every authenticated request.

Each API User has its own key pair and permission scope. Create separate API Users for different environments (development, staging, production) or for different services within your organisation.

Build and Sign Your JWT

Every authenticated request to the Finrock API requires a JWT token signed with RS256 (RSASSA-PKCS1-v1_5 with SHA-256). The JWT payload must contain the following fields:

Field	Type	Description
`uri`	string	The URI path of the request, e.g. `/dac/v1/transactions`
`nonce`	string	A unique string; must differ for every request
`iat`	number	Issued-at timestamp in seconds since Unix Epoch
`exp`	number	Expiry timestamp in seconds since Epoch; must be less than `iat + 30`
`sub`	string	Your API Key UUID
`bodyHash`	string	Hex-encoded SHA-256 hash of the raw HTTP request body

The following Node.js example shows how to build and sign a JWT for an authenticated request:

const fs = require("fs");
const crypto = require("crypto");
const jwt = require("jsonwebtoken");

const privateKey = fs.readFileSync("private_key.pem", "utf8");
const apiKey = "4466c45a-7b28-4c50-a0f7-198f8d7f34c5"; // your API Key UUID

function buildJwt(uriPath, requestBody = "") {
  const now = Math.floor(Date.now() / 1000);

  // Compute SHA-256 hash of the raw request body
  const bodyHash = crypto
    .createHash("sha256")
    .update(requestBody)
    .digest("hex");

  const payload = {
    uri: uriPath,
    nonce: crypto.randomUUID(),
    iat: now,
    exp: now + 25, // must be less than iat + 30
    sub: apiKey,
    bodyHash,
  };

  return jwt.sign(payload, privateKey, { algorithm: "RS256" });
}

// Example: building a JWT for the create-wallet endpoint
const body = JSON.stringify({ asset: "BTC" });
const token = buildJwt("/dac/v1/create-wallet", body);

console.log("Authorization: Bearer " + token);
console.log("x-api-key: " + apiKey);

Attach two headers to every authenticated request:

Authorization: Bearer <your-signed-JWT>
x-api-key: 4466c45a-7b28-4c50-a0f7-198f8d7f34c5

See the Authentication guide for additional language examples and a full breakdown of the JWT specification.

Create a Wallet

With your credentials ready, create your first MPC wallet by posting an asset identifier to the create-wallet endpoint. Finrock provisions the wallet and distributes key shares across your configured MPC nodes.

curl --request POST \
  --url https://api.finrock.io/dac/v1/create-wallet \
  --header 'Authorization: Bearer <JWT>' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"asset": "BTC"}'

Replace <JWT> with a token generated for the URI /dac/v1/create-wallet and the body {"asset":"BTC"}. Replace <your-api-key> with your API Key UUID.On success you receive a 200 response containing the wallet ID and asset details. Save the wallet ID — you will reference it when generating addresses and submitting transactions.

The asset value must match an entry from the supported assets list. Use the exact asset identifier string shown there, for example BTC, ETH, or SOL.

Generate a Deposit Address

Generate a blockchain address under your new wallet to start receiving funds. Each address can be labelled to track its purpose and optionally configured for automatic gas refills.

curl --request POST \
  --url https://api.finrock.io/dac/v1/generate-address \
  --header 'Authorization: Bearer <JWT>' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "asset": "BTC",
    "label": "my-first-address",
    "omnibus": false,
    "auto_refill": false
  }'

The label field helps you identify the address’s purpose later. Setting omnibus: false creates an isolated address dedicated to a single wallet. Set auto_refill: true if you want Finrock to automatically fund gas from your Gas Tank when this address initiates EVM transactions.The response includes the generated blockchain address string that you can share with depositors or use in your payment flows.

Send a Transaction

Submit an outbound transaction from your wallet using the transaction endpoint. Finrock coordinates the MPC signing ceremony across your nodes and broadcasts the signed transaction to the network.

curl --request POST \
  --url https://api.finrock.io/dac/v1/transaction \
  --header 'Authorization: Bearer <JWT>' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "asset": "BTC",
    "amount": 0.001,
    "source_type": "WALLET",
    "destination_type": "ONE_TIME_ADDRESS",
    "destination_id": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }'

Key fields in the transaction request:

Field	Description
`asset`	Asset identifier from the supported assets list
`amount`	Amount to send; up to 8 decimal places of precision
`source_type`	Where funds originate — refer to the source type reference
`destination_type`	Destination category — refer to the destination type reference
`destination_id`	Destination address, label, or account identifier

The response returns a transaction ID and initial status. Transaction signing and network broadcast happen asynchronously; use webhooks to track completion.

Set up a webhook endpoint to receive real-time notifications when your transaction status changes — from pending signature, through network broadcast, to on-chain confirmation. See the Webhooks guide to get started.

Next Steps

You have completed the core integration flow. Explore these topics to build out the rest of your integration:

Authentication Deep Dive

Understand every JWT field, see multi-language code snippets, and review security best practices.

Gas Tanks

Learn how to fund and manage gas tanks so EVM transactions always have enough gas.

AML Controls

Integrate address screening and automatic transaction blocking for compliance.

Webhooks

Subscribe to transaction and wallet events for real-time updates in your application.

Get Started

Core Concepts

Guides

Platform Reference

Get Started with Finrock: Wallets and Transactions

Next Steps

Authentication Deep Dive

Gas Tanks

AML Controls

Webhooks

​Next Steps

Authentication Deep Dive

Gas Tanks

AML Controls

Webhooks

Next Steps