Get set up: keys & onboarding

Step 1: Generate an Ed25519 key pair

Generate the key pair yourself — Onramper never sees your private key.

TypeScript / Node.js

import { generateKeyPairSync } from 'crypto';

const { publicKey, privateKey } = generateKeyPairSync('ed25519', {
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
});

console.log('PUBLIC KEY (send to Onramper):');
console.log(publicKey);

Command line (OpenSSL)

# Generate Ed25519 private key
openssl genpkey -algorithm ED25519 -out private_key.pem

# Extract public key (send this to Onramper)
openssl pkey -in private_key.pem -pubout -out public_key.pem

💡
Public keys use SPKI format; private keys use PKCS8. Both work out of the box with Node.js crypto, Python cryptography, Go crypto/ed25519, and OpenSSL.

💡
Use a separate key pair per environment (dev, staging, production) and register each with its matching API key. Mixing them up is the most common cause of staging signatures failing in production.

Step 2: Send your public key to Onramper

Contact your Onramper account manager or customer support
Provide your public key in PEM format (recommended) or hex format
We'll configure your account and confirm when V2 is enabled

Step 3: Store your private key securely

❗
Your private key must never be exposed. Anyone holding it can sign requests as your organization.

Do: store keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, Google Cloud Secret Manager) or environment variables.

Never: commit private keys to source control, store them in plaintext config files, or expose them in client-side code.

Onboarding requirements

Alongside your public key, provide the following so we can secure your account:

Requirement	Description	Example
Server IPs	Egress IPs (IPv4 + IPv6) your servers use for API calls	`203.0.113.50`
Domains	Domains where the widget is embedded	`app.partner.com`
Extension ID	Browser extension address, if applicable	`chrome-extension://abc...`
Deep links	Mobile app URL schemes	`myapp://`
Redirect URLs	Success/failure callback URL domains	`partner.com/callback`
Security contact	For security notifications	Email, phone
V2 public key	Your Ed25519 public key	PEM or hex

⚠️
Server-side API calls must originate from your whitelisted IPs — requests from other IPs receive 403 Forbidden. Include load balancer, NAT gateway, and failover IPs. If your infrastructure changes, contact support before deploying.

Get set up: keys & onboarding

Step 1: Generate an Ed25519 key pair

Public keys use SPKI format; private keys use PKCS8. Both work out of the box with Node.js `crypto`, Python `cryptography`, Go `crypto/ed25519`, and OpenSSL.

Use a separate key pair per environment (dev, staging, production) and register each with its matching API key. Mixing them up is the most common cause of staging signatures failing in production.

Step 2: Send your public key to Onramper

Step 3: Store your private key securely

Your private key must never be exposed. Anyone holding it can sign requests as your organization.

Onboarding requirements

Server-side API calls must originate from your whitelisted IPs — requests from other IPs receive `403 Forbidden`. Include load balancer, NAT gateway, and failover IPs. If your infrastructure changes, contact support before deploying.

Step 1: Generate an Ed25519 key pair

Public keys use SPKI format; private keys use PKCS8. Both work out of the box with Node.js crypto, Python cryptography, Go crypto/ed25519, and OpenSSL.

Use a separate key pair per environment (dev, staging, production) and register each with its matching API key. Mixing them up is the most common cause of staging signatures failing in production.

Step 2: Send your public key to Onramper

Step 3: Store your private key securely

Your private key must never be exposed. Anyone holding it can sign requests as your organization.

Onboarding requirements

Server-side API calls must originate from your whitelisted IPs — requests from other IPs receive 403 Forbidden. Include load balancer, NAT gateway, and failover IPs. If your infrastructure changes, contact support before deploying.

Public keys use SPKI format; private keys use PKCS8. Both work out of the box with Node.js `crypto`, Python `cryptography`, Go `crypto/ed25519`, and OpenSSL.

Server-side API calls must originate from your whitelisted IPs — requests from other IPs receive `403 Forbidden`. Include load balancer, NAT gateway, and failover IPs. If your infrastructure changes, contact support before deploying.