@turnkey/cosmjs

Turnkey Signer for CosmJS

@turnkey/cosmjs provides TurnkeyDirectWallet, a drop-in replacement for CosmJS’s DirectSecp256k1Wallet. It conforms to the OfflineDirectSigner interface, so it works with any CosmJS SigningStargateClient or compatible client.

This package is experimental. Cosmos chain support is functional but the API may evolve.

Installation

npm

npm install @turnkey/cosmjs

Usage

1. Create a Turnkey client

   import { TurnkeyClient } from "@turnkey/http";
   import { ApiKeyStamper } from "@turnkey/api-key-stamper";
   
   const turnkeyClient = new TurnkeyClient(
     { baseUrl: "https://api.turnkey.com" },
     new ApiKeyStamper({
       apiPublicKey: "your-api-public-key",
       apiPrivateKey: "your-api-private-key",
     }),
   );
   
2. Initialize TurnkeyDirectWallet

   Use TurnkeyDirectWallet.init to create the wallet. Pass a Bech32 prefix to match the target chain.

   import { TurnkeyDirectWallet } from "@turnkey/cosmjs";
   
   const wallet = await TurnkeyDirectWallet.init({
     config: {
       client: turnkeyClient,
       organizationId: "your-organization-id",
       // Pass a wallet account public key (uncompressed hex) or a private key ID (UUID)
       signWith: "your-public-key-or-private-key-id",
     },
     // Bech32 prefix for the chain — defaults to "cosmos"
     prefix: "celestia",
   });
   

   If signWith is a UUID (private key ID), init fetches the public key from the Turnkey API. If it is a hex public key, compression is handled locally without a network call.

3. Sign and broadcast a transaction

   Connect the wallet to a SigningStargateClient and use standard CosmJS APIs.

   import { SigningStargateClient } from "@cosmjs/stargate";
   
   const rpcUrl = "https://rpc.celestia-testnet.example.com";
   const signingClient = await SigningStargateClient.connectWithSigner(
     rpcUrl,
     wallet,
   );
   
   const [account] = await wallet.getAccounts();
   
   const result = await signingClient.sendTokens(
     account.address,
     "recipient-bech32-address",
     [{ denom: "utia", amount: "1000" }],
     { amount: [{ denom: "utia", amount: "500" }], gas: "200000" }, // fee
   );
   
   console.log(`Transaction hash: ${result.transactionHash}`);
   

TurnkeyDirectWallet.init options

config.client · TurnkeyClient | TurnkeyBrowserClient | TurnkeyServerClient | TurnkeySDKClientBase · required

A Turnkey client instance.

config.organizationId · string · required

Your Turnkey organization ID (or sub-organization ID).

config.signWith · string · required

A wallet account public key (uncompressed hex) or a private key ID (UUID). If a UUID is provided, the public key is fetched from the Turnkey API.

prefix · string

The Bech32 address prefix for the target chain (e.g., "cosmos", "celestia", "osmo"). Defaults to "cosmos".

Synchronous initialization

If you already have an uncompressed public key and want to avoid an async API call, use TurnkeyDirectWallet.initWithPublicKey:

const wallet = TurnkeyDirectWallet.initWithPublicKey({
  config: {
    client: turnkeyClient,
    organizationId: "your-organization-id",
    signWith: "uncompressed-hex-public-key",
  },
  prefix: "cosmos",
});

Available methods

TurnkeyDirectWallet implements the OfflineDirectSigner interface:

Method	Description
getAccounts()	Returns an array with a single AccountData entry containing the address, algorithm (secp256k1), and public key.
signDirect(address, signDoc)	Signs a Cosmos SignDoc using Turnkey and returns a DirectSignResponse.

Supported chains

TurnkeyDirectWallet works with any Cosmos SDK chain that supports secp256k1 signing and the SIGN_MODE_DIRECT signing mode. Examples include:

• Cosmos Hub (cosmos)
• Celestia (celestia)
• Osmosis (osmo)
• Any chain with a custom Bech32 prefix

Examples

• with-cosmjs: create a new Cosmos address, then sign and broadcast a transaction on Celestia testnet via CosmJS