Ephemeral accounts are temporary blockchain accounts created for a single ramp. The SDK creates a fresh Substrate (sr25519) account and a fresh EVM (secp256k1) account per ramp; one of each covers every leg of the route. They may hold funds in transit while Vortex coordinates swaps, transfers, bridge operations, or payment settlement.Vortex receives only ephemeral public addresses. Vortex does not receive, store, log, or reconstruct ephemeral secret keys.This is a critical integration responsibility:The API client or SDK environment must store ephemeral secrets securely.
Secrets must remain available until the ramp is complete and any recovery window has passed.
Secrets must never be sent to Vortex endpoints, support channels, logs, or analytics. In a browser SDK integration they necessarily exist in browser-visible memory and, by default, same-origin localStorage.
If ephemeral secrets are lost, the partner may be unable to complete recovery for that ramp. Vortex has chain-specific cleanup mechanisms that can recover funds in some cases, but partners should not rely on this for normal operation.
storeEphemeralKeys, which defaults to true. In Node.js environments, it writes ephemerals_{rampId}.json to the process's current working directory. In browsers, it writes the same plaintext JSON under that key in same-origin localStorage. Neither form is encrypted at rest.For encrypted, vault-backed, or otherwise application-managed persistence, configure storeEphemeralKeysCallback:The callback receives an array of StoredEphemeralKey objects ({ address, rampId, secret, type }) and the ramp ID. When configured, it replaces the built-in file or localStorage backup, and storeEphemeralKeys has no effect. The callback owns the storage destination, encryption, access controls, and retention policy; the SDK still does not send the secrets to Vortex.Persistence is fail-closed for both the built-in backup and the custom callback. The SDK waits for storage after the API creates the ramp but before it signs ephemeral-owned transactions or submits the ramp update. If the write or callback fails, registerRamp() rejects and does not continue to the update or start steps. The backend registration may remain incomplete until it expires, but the SDK does not report a usable ramp while its recovery keys are unprotected. Storage errors are deliberately propagated rather than logged and ignored.Treat all backups as sensitive key material. For built-in Node.js storage, restrict filesystem permissions and exclude files from source control. Browser localStorage is prototype-grade: every same-origin script can read it, and the SDK does not prune terminal entries automatically. For custom storage, keep the callback available and deterministic throughout registration, and retain the keys until the operational recovery window has passed. Setting storeEphemeralKeys: false without a callback disables backup entirely; it does not expose the secrets through another SDK mechanism.Direct API integrations must implement equivalent custody behavior. At minimum, they should create fresh ephemerals per ramp, store encrypted backups, associate backups with the ramp ID, and verify that recovery material exists before allowing the user to continue.
Modified at 2026-09-01 13:38:13
