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

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.
2 subfields

Returns

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

Example

Send a DelegateTx

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.
1 subfields

Returns

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

Example

Send a RevokeDelegateTx

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

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

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.
6 subfields
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

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

// 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

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

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

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

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

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.
2 subfields
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

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

// 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

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

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

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

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