Skip to main content

High-level API

Transaction helpers are high-level functions built into the OCAP Client that abstract away the complexity of creating and signing common transactions. Instead of manually constructing transaction objects, you can use these convenient methods for workflows like creating assets, transferring tokens, staking, and performing atomic swaps. These helpers ensure that the transaction structure is correct and simplify the development process significantly.

For a deeper understanding of the underlying transaction lifecycle, see Core Concepts: Transaction Lifecycle.

Account Management

migrateAccount

Migrates the ownership of an account to a new key pair. This is useful for key rotation or account recovery.

Parameters

  • from WalletObject (required) — The wallet object of the account to migrate from.
  • to WalletObject (required) — The wallet object of the account to migrate to.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send an AccountMigrateTx

javascript
const txHash = await client.migrateAccount({
  from: oldWallet,
  to: newWallet,
});
console.log('Migration transaction hash:', txHash);

delegate

Authorizes another account (the delegatee) to send specific types of transactions on behalf of the delegator. This is a powerful feature for creating secure, sandboxed permissions.

Parameters

  • from WalletObject (required) — The delegator's wallet, who is granting the privilege.
  • to WalletObject (required) — The delegatee's wallet, who is receiving the privilege.
  • privileges array (required) — An array of privilege objects specifying the allowed actions.
    • typeUrl string (required) — The type URL of the transaction being permitted (e.g., 'fg:t').
    • limit object — Optional limits on the delegation.
      • tokens array — Limits on specific fungible tokens.
      • assets array — Limits on specific assets (NFTs).

Returns

  • result Promise<[string, string]> — An array containing the transaction hash and the newly created delegate address.

Example

Send a DelegateTx

javascript
const [txHash, delegateAddress] = await client.delegate({
  from: userWallet,
  to: appWallet,
  privileges: [
    {
      typeUrl: 'fg:t:transfer_v2',
    },
  ],
});
console.log('Delegation tx hash:', txHash);
console.log('Delegate address:', delegateAddress);

revokeDelegate

Revokes previously granted permissions from a delegatee.

Parameters

  • from WalletObject (required) — The delegator's wallet.
  • to WalletObject (required) — The delegatee's wallet.
  • privileges array (required) — An array of privilege objects specifying the permissions to revoke.
    • typeUrl string (required) — The type URL of the transaction to revoke (e.g., 'fg:t').

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a RevokeDelegateTx

javascript
const txHash = await client.revokeDelegate({
  from: userWallet,
  to: appWallet,
  privileges: ['fg:t:transfer_v2'],
});
console.log('Revocation tx hash:', txHash);

Asset (NFT) Management

createAsset

Creates a new asset (Non-Fungible Token) on the blockchain.

Parameters

  • moniker string (required) — A short, human-readable name for the asset.
  • data object (required) — A JSON object containing the asset's metadata.
  • wallet WalletObject (required) — The wallet of the asset's initial owner.
  • parent string — The address of a parent asset, establishing a hierarchical link.
  • ttl number (default: 0) — Time-to-live in seconds after the first consumption.
  • readonly boolean (default: false) — If true, the asset cannot be updated after creation.
  • transferrable boolean (default: true) — If true, the asset can be transferred to another account.
  • display object — Object for asset display metadata.
  • endpoint object — Object for asset endpoint metadata.
  • tags string[] — An array of tags for categorization.
  • delegator string — The address of the delegator, if the transaction is sent by a delegatee.

Returns

  • result Promise<[string, string]> — An array containing the transaction hash and the address of the newly created asset.

Example

Send a CreateAssetTx

javascript
const [txHash, assetAddress] = await client.createAsset({
  moniker: 'My First NFT',
  data: {
    typeUrl: 'json',
    value: { name: 'Digital Collectible', description: 'A unique item.' },
  },
  wallet: userWallet,
});
console.log('Create asset tx hash:', txHash);
console.log('New asset address:', assetAddress);

updateAsset

Updates the moniker and data fields of an existing, non-readonly asset.

Parameters

  • address string (required) — The address of the asset to update.
  • moniker string (required) — The new moniker for the asset.
  • data object (required) — The new JSON data object for the asset.
  • wallet WalletObject (required) — The wallet of the asset's current owner.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send an UpdateAssetTx

javascript
const txHash = await client.updateAsset({
  address: 'z3g...',
  moniker: 'Updated NFT Name',
  data: {
    typeUrl: 'json',
    value: { name: 'Updated Collectible', description: 'Now with more features!' },
  },
  wallet: userWallet,
});
console.log('Update asset tx hash:', txHash);

createAssetFactory

Creates an asset factory, which acts as a template for minting multiple new assets with a consistent structure.

Parameters

  • factory object (required) — An object containing the factory's configuration.
    • name string (required) — Name of the factory.
    • description string (required) — Description of the factory.
    • limit number (default: 0) — The maximum number of assets that can be minted (0 for unlimited).
    • trustedIssuers string[] — A list of wallet addresses allowed to mint from this factory.
    • input object (required) — Defines the inputs required for minting.
    • output object (required) — Defines the structure of the minted asset, often using templates.
  • wallet WalletObject (required) — The wallet to own the factory.

Returns

  • result Promise<[string, string]> — An array containing the transaction hash and the address of the newly created factory.

Example

Send a CreateFactoryTx

javascript
const factoryConfig = {
  name: 'Ticket Factory',
  description: 'Mints event tickets',
  limit: 1000,
  input: { ... },
  output: { ... },
};

const [txHash, factoryAddress] = await client.createAssetFactory({
  factory: factoryConfig,
  wallet: eventCreatorWallet,
});
console.log('Create factory tx hash:', txHash);
console.log('New factory address:', factoryAddress);

acquireAsset

Acquires (mints) a new asset from an existing asset factory. This is typically initiated by the end-user who will own the asset.

Parameters

  • itx AcquireAssetV2Tx (required) — The inner transaction object, often prepared using a helper like preMintAsset.
  • wallet WalletObject (required) — The wallet of the user acquiring the asset.
  • delegator string — The address of the delegator, if applicable.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send an AcquireAssetV2Tx

javascript
// First, prepare the minting transaction (e.g., on the server)
const itx = await client.preMintAsset({
  factory: factoryAddress,
  owner: userWallet.address,
  wallet: issuerWallet,
});

// Then, the user sends the transaction
const txHash = await client.acquireAsset({ itx, wallet: userWallet });
console.log('Acquire asset tx hash:', txHash);

mintAsset

This is the issuer-side counterpart to acquireAsset. It allows a trusted issuer to mint an asset from a factory and assign it to a specified owner.

Parameters

  • itx MintAssetTx (required) — The inner transaction object, often prepared using preMintAsset.
  • wallet WalletObject (required) — The wallet of the trusted issuer.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a MintAssetTx

javascript
const itx = await client.preMintAsset({
  factory: factoryAddress,
  owner: userWallet.address,
  wallet: issuerWallet,
});

const txHash = await client.mintAsset({ itx, wallet: issuerWallet });
console.log('Mint asset tx hash:', txHash);

Token Management

createTokenFactory

Creates a new factory for minting and burning a specific fungible token, often based on a bonding curve pricing model.

Parameters

  • feeRate number (default: 0) — The fee rate for minting and burning operations.
  • curve object (required) — The bonding curve configuration for pricing.
  • token object (required) — The configuration for the token to be created. This includes properties like name, symbol, decimal, and maxTotalSupply.
  • data object — Optional metadata for the token factory.
  • wallet WalletObject (required) — The wallet of the factory's owner.

Returns

  • result Promise<[string, string]> — An array containing the transaction hash and the address of the newly created token factory.

Example

Send a CreateTokenFactoryTx

javascript
const [txHash, factoryAddress] = await client.createTokenFactory({
  feeRate: 100, // 1%
  curve: { fixedPrice: '1' }, // 1 native token per new token
  token: {
    name: 'My Community Token',
    symbol: 'MCT',
    decimal: 18,
    maxTotalSupply: '1000000',
  },
  wallet: creatorWallet,
});
console.log('Create token factory tx hash:', txHash);
console.log('New token factory address:', factoryAddress);

updateTokenFactory

Updates the feeRate and data for an existing token factory.

Parameters

  • address string (required) — The address of the token factory to update.
  • feeRate number — The new fee rate for minting and burning.
  • data object — New metadata for the token factory.
  • wallet WalletObject (required) — The wallet of the factory's owner.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send an UpdateTokenFactoryTx

javascript
const txHash = await client.updateTokenFactory({
  address: 'z2f...',
  feeRate: 50, // 0.5%
  wallet: ownerWallet,
});
console.log('Update token factory tx hash:', txHash);

mintToken

Mints new tokens from a token factory in exchange for the reserve token (usually the native chain token). The cost is determined by the factory's bonding curve.

Parameters

  • tokenFactory string (required) — The address of the token factory.
  • amount number (required) — The amount of new tokens to mint.
  • receiver string (required) — The address that will receive the newly minted tokens.
  • maxReserve number (required) — The maximum amount of reserve tokens the user is willing to pay. This acts as slippage protection.
  • data object — Optional metadata for the transaction.
  • wallet WalletObject (required) — The wallet initiating the mint.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a MintTokenTx

javascript
const txHash = await client.mintToken({
  tokenFactory: 'z2f...',
  amount: 100,
  receiver: userWallet.address,
  maxReserve: 105, // Willing to pay up to 105 native tokens
  wallet: userWallet,
});
console.log('Mint token tx hash:', txHash);

burnToken

Burns existing tokens at a factory to receive the underlying reserve token in return. The amount of reserve token received is determined by the factory's bonding curve.

Parameters

  • tokenFactory string (required) — The address of the token factory.
  • amount number (required) — The amount of tokens to burn.
  • receiver string (required) — The address that will receive the reserve tokens.
  • minReserve number (required) — The minimum amount of reserve tokens the user expects to receive. This acts as slippage protection.
  • data object — Optional metadata for the transaction.
  • wallet WalletObject (required) — The wallet initiating the burn.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a BurnTokenTx

javascript
const txHash = await client.burnToken({
  tokenFactory: 'z2f...',
  amount: 50,
  receiver: userWallet.address,
  minReserve: 48, // Expecting to receive at least 48 native tokens
  wallet: userWallet,
});
console.log('Burn token tx hash:', txHash);

Transfer & Exchange

transfer

Transfers native tokens, custom fungible tokens, and/or assets (NFTs) to another account in a single transaction.

Parameters

  • to string (required) — The address of the recipient.
  • wallet WalletObject (required) — The sender's wallet.
  • token number (default: 0) — The amount of the chain's native token to transfer.
  • assets string[] — An array of asset addresses (NFTs) to transfer.
  • tokens object[] — An array of custom fungible token objects to transfer.
    • address string (required) — The address of the custom token contract.
    • value number (required) — The amount of the custom token to transfer.
  • memo string — An optional note for the transaction.
  • delegator string — The delegator's address, if applicable.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a TransferV2Tx

javascript
const txHash = await client.transfer({
  to: 'z1sb...',
  token: 1.5, // 1.5 of the native chain token
  assets: ['z3g...'], // An NFT
  tokens: [{ address: 'z2t...', value: 100 }], // 100 of a custom token
  memo: 'Payment for services',
  wallet: senderWallet,
});
console.log('Transfer tx hash:', txHash);

prepareExchange

Prepares the sender's half of an atomic swap (exchange) transaction. It signs the sender's offer and returns a transaction object that can be passed to the receiver.

Parameters

  • receiver string (required) — The address of the other party in the exchange.
  • wallet WalletObject (required) — The wallet of the user making the offer.
  • offerToken number — Amount of native token offered.
  • offerAssets string[] — Array of asset addresses offered.
  • offerTokens object[] — Array of custom fungible tokens offered.
  • demandToken number — Amount of native token demanded in return.
  • demandAssets string[] — Array of asset addresses demanded in return.
  • demandTokens object[] — Array of custom fungible tokens demanded.
  • memo string — An optional note for the transaction.

Returns

  • transactionObject Promise<object> — The partially signed transaction object.

finalizeExchange

Finalizes the receiver's half of an atomic swap. It takes the partially signed transaction from prepareExchange, adds the receiver's signature, and returns the fully signed transaction object.

Parameters

  • tx object (required) — The transaction object returned from prepareExchange.
  • wallet WalletObject (required) — The wallet of the user accepting the offer.
  • data object — Extra data in the multi-signature.

Returns

  • transactionObject Promise<object> — The fully signed, multi-signature transaction object.

exchange

Sends the fully signed exchange transaction to the blockchain. This can be called by either party after finalizeExchange is complete.

Parameters

  • tx object (required) — The transaction object returned from finalizeExchange.
  • wallet WalletObject (required) — The wallet of the user submitting the transaction.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example (Full Exchange Flow)

Perform an atomic swap

javascript
// 1. Offerer prepares the transaction
const offerTx = await client.prepareExchange({
  receiver: receiverWallet.address,
  offerAssets: ['z3g...'], // Offer an NFT
  demandToken: 10, // Demand 10 native tokens
  wallet: offererWallet,
});

// 2. Receiver finalizes the transaction
const finalTx = await client.finalizeExchange({
  tx: offerTx,
  wallet: receiverWallet,
});

// 3. Either party can send the finalized transaction
const txHash = await client.exchange({ tx: finalTx, wallet: offererWallet });
console.log('Exchange tx hash:', txHash);

Staking

stake

Stakes tokens and/or assets to a receiver address. Staking locks up resources, often in exchange for rewards or to provide security.

Parameters

  • to string (required) — The address of the stake receiver.
  • wallet WalletObject (required) — The wallet of the staker.
  • assets string[] — An array of asset addresses to stake.
  • tokens object[] — An array of fungible token objects to stake.
  • locked boolean (default: false) — Whether the stake is locked upon creation.
  • slashers string[] — A list of addresses that are permitted to slash this stake.
  • message string — An optional note for the stake.

Returns

  • result Promise<[string, string]> — An array containing the transaction hash and the address of the newly created stake.

Example

Send a StakeTx

javascript
const [txHash, stakeAddress] = await client.stake({
  to: 'z1v...',
  tokens: [{ address: 'z2t...', value: 5000 }],
  message: 'Staking for validator rewards',
  wallet: userWallet,
});
console.log('Stake tx hash:', txHash);
console.log('New stake address:', stakeAddress);

revokeStake

Revokes previously staked tokens and/or assets, initiating the process to return them to the owner. Note that there may be an unbonding period before the assets can be claimed.

Parameters

  • from string (required) — The address of the stake to revoke from.
  • wallet WalletObject (required) — The wallet of the stake owner.
  • assets string[] — An array of asset addresses to revoke.
  • tokens object[] — An array of fungible token objects to revoke.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a RevokeStakeTx

javascript
const txHash = await client.revokeStake({
  from: 'z6s...',
  tokens: [{ address: 'z2t...', value: 1000 }],
  wallet: userWallet,
});
console.log('Revoke stake tx hash:', txHash);

claimStake

Claims items from a stake that have been successfully revoked and have passed their unbonding period.

Parameters

  • from string (required) — The address of the stake to claim from.
  • evidence string (required) — The transaction hash of the revokeStake transaction.
  • wallet WalletObject (required) — The wallet of the stake owner.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a ClaimStakeTx

javascript
const revokeTxHash = '0x123...abc';
const txHash = await client.claimStake({
  from: 'z6s...',
  evidence: revokeTxHash,
  wallet: userWallet,
});
console.log('Claim stake tx hash:', txHash);

slashStake

Allows a designated slasher to penalize a stake, typically for misbehavior. The slashed assets are transferred to a designated vault address.

Parameters

  • from string (required) — The address of the stake to slash.
  • reason string (required) — A message explaining the reason for slashing.
  • wallet WalletObject (required) — The wallet of the designated slasher.
  • assets string[] — An array of asset addresses to slash.
  • tokens object[] — An array of fungible token objects to slash.

Returns

  • transactionHash Promise<string> — The hash of the submitted transaction.

Example

Send a SlashStakeTx

javascript
const txHash = await client.slashStake({
  from: 'z6s...',
  reason: 'Validator downtime',
  tokens: [{ address: 'z2t...', value: 500 }],
  wallet: slasherWallet,
});
console.log('Slash stake tx hash:', txHash);