API Access Key

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.

Before you begin: add an API user

To use the Finrock API, you need an API user in your Finrock workspace. The API user is what gives your application API access, and it controls which sub-accounts your application can use.

Add a new user

In the Finrock dashboard, go to Users, click Add new user, and select API User.

Enter a title

Give the API user a name you’ll recognise, such as the name of your app or environment (for example Production backend).

Add your public key

Under Public Key (RSA 4096), add your public key. You have two options:

Generate keys on your own machine, then paste or Upload your public key. The Generate Your RSA Key Pair tab below shows how.
Generate keys in Finrock: click Generate and the Finrock dashboard creates the key pair for you.

Choose sub-accounts

Under Sub Accounts, select the sub-accounts this API user can access, such as Main Account.

Save and get approval

Click Save. The owner, or at least 2 admins, must approve the new API user before it can make API requests. Once approved, the API user shows as Active in your users list.

Copy your API key

In your users list, find the API user and click the key icon. Copy the API key using the copy button next to it. It looks like 4466c45a-7b28-4c50-a0f7-198f8d7f34c5.In the same window, you can add your server’s IP addresses under IP Whitelist so only those addresses can use this API user. See Whitelist IPs.

Create a separate API user for each environment (development, staging, production) and give each one access to only the sub-accounts it needs.

Generate Your RSA Key Pair
Get Your API Key
Build and Sign Your JWT

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 it securely and never commit it to source control. Do not share it with anyone, not even with Finrock.
public_key.pem: paste this key in Finrock when adding an API user.

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.

Copy your API key from your API user, as described in Before you begin. It looks like 4466c45a-7b28-4c50-a0f7-198f8d7f34c5.You will need this key 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.

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

Make Your First Requests

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/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/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": "Internal",
    "destination_type": "External",
    "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.

Connect Claude to Finrock MCP

Building with an AI agent? Connect Claude to the Finrock MCP server to generate working integrations.

Get Started

Core Concepts

Guides

AI Agents

Platform Reference

Before you begin: add an API user

Make Your First Requests

Next Steps

Authentication Deep Dive

Gas Tanks

AML Controls

Webhooks

Connect Claude to Finrock MCP