aptos-petra-connect

Build transactions in Node.js. Approve them in Petra or a connected Ledger—without storing a signing key in local files.

The problem it solves

A script that submits Aptos transactions commonly loads a private key from an .env file, key file, or local secret store and signs directly in the process. That makes the developer machine or automation environment responsible for protecting a key that can authorize every transaction.

aptos-petra-connect separates transaction construction from signing. The Node.js script builds the payload and waits, while Petra shows the request and signs only after the user approves it. If a Ledger hardware wallet is connected through Petra, the same bridge can use that Ledger-backed account without exporting the device's private key.

| Without this library | With aptos-petra-connect | | --- | --- | | Store a private key in .env, a key file, or a local secret | Keep software-wallet keys in Petra or hardware-wallet keys on Ledger | | Let the script construct and sign the transaction | Let the script construct it and the wallet approve it | | Build a custom browser-to-process handoff | Use one Promise-based API | | Approve without a dedicated request summary | Review the function, network, recipient, and amount |

How it works

sequenceDiagram
    participant Script as Node.js script
    participant Bridge as Local bridge
    participant Browser as Browser review
    participant Petra as Petra wallet

    Script->>Bridge: requestTransaction(...)
    Bridge->>Browser: Open localhost request page
    Browser->>Bridge: Load transaction payload
    Browser->>Petra: Connect and request signature
    Petra-->>Browser: Approved wallet result
    Note over Browser: User clicks Continue to script
    Browser->>Bridge: Return sender and hash
    Bridge-->>Script: Resolve RequestData

The local page only coordinates the request and its result. Petra-managed keys stay in Petra, and a Ledger-backed private key stays on the hardware device.

Installation

npm install aptos-petra-connect

Quick start: transfer APT

import { AptosPetraConnect, Network } from 'aptos-petra-connect';

async function main() {
  const connector = new AptosPetraConnect(Network.TESTNET);

  try {
    const recipientAddress = '0x...';
    const amountInOcta = '100000000'; // 1 APT

    const { hash, sender } = await connector.requestTransaction({
      title: 'Transfer APT',
      callType: 'function',
      txData: {
        function: '0x1::aptos_account::transfer',
        typeArguments: [],
        functionArguments: [recipientAddress, amountInOcta],
      },
    });

    console.log('Sender:', sender);
    console.log('Transaction hash:', hash);
  } finally {
    connector.close();
  }
}

main().catch(console.error);

When requestTransaction() runs, the script waits while the browser and Petra handle the approval. Press Continue to script after signing to resolve the Promise.

Common recipes

Get the connected wallet address

const { sender } = await connector.requestTransaction({
  title: 'Connect Petra Wallet',
  callType: 'walletAddress',
});

console.log('Connected wallet:', sender);

Call any entry function

const result = await connector.requestTransaction({
  title: 'Mint NFT',
  callType: 'function',
  txData: {
    function: `${moduleAddress}::collection::mint`,
    typeArguments: [],
    functionArguments: [collectionName, tokenName],
  },
});

console.log(result.hash);

Deploy a Move package to an object

const { deployAddress, hash } = await connector.deployModuleOnObject({
  projectPath: '/absolute/path/to/move-package',
  defaultAddressName: 'my_module',
});

console.log('Object address:', deployAddress);
console.log('Transaction hash:', hash);

Pass upgradeAddress to the same method when upgrading an existing object deployment.

await connector.deployModuleOnObject({
  projectPath: '/absolute/path/to/move-package',
  defaultAddressName: 'my_module',
  upgradeAddress: '0x...',
});

Deploy a Move package to the connected account

const { deployAddress, hash } = await connector.deployModuleOnAccount({
  projectPath: '/absolute/path/to/move-package',
  defaultAddressName: 'my_module',
});

API

new AptosPetraConnect(network, port?)

Creates the local bridge immediately.

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | network | Network | required | Aptos network Petra must use | | port | number | automatically assigned | Optional fixed port for the local bridge |

Methods

| Method | Purpose | | --- | --- | | requestTransaction(params) | Request a wallet address or signed entry-function transaction | | deployModuleOnObject(params) | Build and publish or upgrade a Move package through object deployment | | deployModuleOnAccount(params) | Build and publish a Move package to the connected account | | close() | Stop the HTTP server and release its port |

RequestPetraParams

| Field | Type | Required | Description | | --- | --- | --- | --- | | title | string | yes | Human-readable request title shown in the browser | | callType | 'walletAddress' \| 'function' | yes | Address connection or transaction request | | txData | InputEntryFunctionData | for function | Entry-function payload passed to Petra |

RequestData

| Field | Type | Description | | --- | --- | --- | | success | boolean | Whether Petra completed the request successfully | | sender | string | Connected account address | | hash | string? | Submitted transaction hash | | deployAddress | string? | Address calculated by a deployment helper | | error | string? | Wallet or transaction error returned to the script |

Error handling

Rejected or failed wallet requests throw PetraWalletError.

import { AptosPetraConnect, Network, PetraWalletError } from 'aptos-petra-connect';

const connector = new AptosPetraConnect(Network.TESTNET);

try {
  await connector.requestTransaction({
    title: 'Example request',
    callType: 'function',
    txData,
  });
} catch (error) {
  if (error instanceof PetraWalletError) {
    console.error('Petra rejected or failed the request:', error.message);
  }
} finally {
  connector.close();
}

Requirements and current limitations

• Node.js 18 or newer
• macOS: the current browser launcher uses the macOS open command
• Petra browser extension installed in the default browser; a Ledger account connected through Petra is optional
• Aptos CLI only when using the Move deployment helpers
• The local bridge binds to 127.0.0.1 and uses an automatically assigned available port by default

The request Promise waits until the browser returns a result. Keep the script running, finish the wallet flow, and always call close() when the process is done.

Security notes

• Petra coordinates every connection and signature request; Ledger-backed accounts keep the private key on the hardware device.
• The browser page never asks for a private key or recovery phrase.
• Verify the network, function, recipient, amount, and arguments before approving.
• The bridge is intended for local development workflows. Do not expose its port to an untrusted network.
• Use try/finally so the local server is closed even when a request fails.

Development

npm install
npm run build

License

MIT