Signing keys

API keys authenticate requests to Pvium. Signing keys authorize payout operations: your organization’s signing key finalizes payouts, and payout keys let services execute payments from a specific funded pool.

The signing key — your finalization key

Your organization’s signing key signs the payout details when you finalize a payout. The smart contract verifies this signature before executing the authorized payout. To create or register your organization’s signing key in the dashboard:

Open your organization settings and go to the Signing Keys tab.
Add a key: give it a label, choose the key type (Ethereum), and either paste a public key or generate a fresh keypair in place.
If you generate, copy the private key immediately and store it in backend configuration — Pvium keeps only the public key.

On your backend, create a signer from the private key and pass that signer to finalize:

import { createSignerFromPrivateKey } from '@pvium/sdk';

const signer = createSignerFromPrivateKey(process.env.PVIUM_SIGNER_KEY!);
const finalized = await payout.finalize(signer);

Anyone with access to this private key can sign payout finalizations. Restrict access to the key and require your team’s approval before funding payouts. See Security for the funding approval flow.

Payout keys — pooled payouts only

A payout key lets a service execute payments from a specific Pooled payout batch. The signer that funded the batch must authorize the payout key and set these limits:

Limit	Meaning
Per-transaction max	The most a single payout transaction can move
Total max	The most the key can pay from this pool under the authorization
Expiration	When the key’s authorization to pay from this pool expires

The signed authorization specifies the pool, payout key, spending limits, and expiration. It does not permit payments from other pools, payments above those limits, or payments after expiration. Give your automated service the payout key’s private key so it can pay from the pool within these limits. The service does not need your organization’s signing key. A payout token is the signed authorization that grants a payout key permission to pay from a pool. You can create one in the dashboard or with the SDK.

Create a payout token in the dashboard

To create a payout token in the dashboard, open a funded, activated pool batch and connect the wallet that funded it. Select Add Payout Key, then provide:

A label (for example, “Production Key”)
The key type (Ethereum)
The public key — paste one, or generate a fresh keypair in place. If you generate, copy and store the private key immediately; Pvium does not keep it.
The per-transaction max, total max, and expiration in days

Create a payout token with the SDK

Call pvium.payout.authorizeSigningKey to create a payout token for a pool. Pass the pool’s batch hash, the payout key’s public address, its network type, spending limits, and expiration as a Unix timestamp in seconds. Sign with the signer that funded the batch. The method returns a signed authorization containing these details and the signature:

const authorization = await pvium.payout.authorizeSigningKey(
  batchHash, // the finalized pool batch this key may act on
  delegateAddress, // the payout key's public address
  'ethereum',
  {
    transactionMax: '500',
    totalMax: '5000',
    expiration: String(Math.floor(Date.now() / 1000) + 86400), // expires in 24 hours
  },
  signer, // must match the batch's funding signer
);

Key custody stays with you

You keep control of the private keys used for finalization and pooled payments:

Pvium registers only the public key. Whether you generate the keypair or bring your own, the private key stays on your system — it is never sent to or stored by Pvium.
Custom signers can be injected. Both finalize and authorizeSigningKey accept a signing function in place of a raw private key, so signing can be delegated to AWS KMS, an HSM, or any other signing module. The private key never has to exist in application memory — the SDK only ever sends the resulting signatures.

Which key for what

Key	Held by	Can do	Cannot do
API key	Your backend	Create and manage payout records	Move money
Signing key	Your backend	Finalize payouts; authorize payout keys for batches it funded	Authorize payout keys for batches funded by another signer
Payout key	An operational service	Pay out of one pool, within its caps	Exceed caps, outlive expiration, touch other batches

Keep API keys and private signing keys out of client-side code. See Authentication for handling guidance.

Get started

Payout automation

Concepts

The signing key — your finalization key

Payout keys — pooled payouts only

Create a payout token in the dashboard

Create a payout token with the SDK

Key custody stays with you

Which key for what

​The signing key — your finalization key

​Payout keys — pooled payouts only

​Create a payout token in the dashboard

​Create a payout token with the SDK

​Key custody stays with you

​Which key for what

The signing key — your finalization key

Payout keys — pooled payouts only

Create a payout token in the dashboard

Create a payout token with the SDK

Key custody stays with you

Which key for what