Skip to main content
The NEAR gas helpers provide convenient functions for working with gas amounts, handling conversions between gas units and TerraGas.

​
Overview

1 TerraGas = 10^12 gas units The library provides both “safe” variants (return Result types) and “throwable” variants (throw errors) for all functions.

​
Functions

​
gas()

Creates a NearGas object from gas units. 
import { gas } from '@near-api/universal';

const gasAmount = gas(300000000000000n);
console.log(gasAmount.gas);      // 300000000000000n
console.log(gasAmount.teraGas);  // "300"
Parameters:
  • gas (bigint | number): Amount in gas units
Returns: NearGas Safe variant: safeGas()

​
teraGas()

Creates a NearGas object from TerraGas. 
import { teraGas } from '@near-api/universal';

const gasAmount = teraGas('300');
console.log(gasAmount.gas);      // 300000000000000n
console.log(gasAmount.teraGas);  // "300"
Parameters:
  • teraGas (string): Amount in TerraGas with up to 12 decimal places
Returns: NearGas Safe variant: safeTeraGas()

​
nearGas()

Creates a NearGas object from either gas units or TerraGas. 
import { nearGas } from '@near-api/universal';

// From gas units
const gas1 = nearGas({ gas: 300000000000000n });

// From TerraGas
const gas2 = nearGas({ teraGas: '300' });
Parameters:
  • args (object): Either { gas: bigint | number } or { teraGas: string }
Returns: NearGas Safe variant: safeNearGas()

​
isNearGas()

Type guard to check if a value is a NearGas object. 
import { isNearGas, gas } from '@near-api/universal';

const gasAmount = gas(300000000000000n);
console.log(isNearGas(gasAmount)); // true

​
NearGas Object

The NearGas object provides the following properties and methods:

​
Properties

  • gas (bigint): Amount in gas units (lazy-loaded)
  • teraGas (string): Amount in TerraGas (lazy-loaded)

​
Methods

​
add()

Add two gas amounts. 
const gas1 = teraGas('100');
const gas2 = teraGas('50');
const result = gas1.add(gas2);
console.log(result.teraGas); // "150"
Safe variant: safeAdd()

​
sub()

Subtract gas amounts. 
const gas1 = teraGas('100');
const gas2 = teraGas('30');
const result = gas1.sub(gas2);
console.log(result.teraGas); // "70"
Safe variant: safeSub()

​
gt()

Compare if greater than. 
const gas1 = teraGas('100');
const gas2 = teraGas('50');
console.log(gas1.gt(gas2)); // true
Safe variant: safeGt()

​
lt()

Compare if less than. 
const gas1 = teraGas('50');
const gas2 = teraGas('100');
console.log(gas1.lt(gas2)); // true
Safe variant: safeLt()

​
Type Definitions

See NearGas Types for complete type information.

​
Examples

​
Basic Usage

import { gas, teraGas } from '@near-api/universal';

// Create from gas units
const gas1 = gas(300000000000000n);

// Create from TerraGas
const gas2 = teraGas('100');

// Perform operations
const sum = gas1.add(gas2);
console.log(sum.teraGas); // "400"

​
Safe Operations

import { safeTeraGas } from '@near-api/universal';

const result = safeTeraGas('300');

if (result.ok) {
  console.log(result.value.gas);
} else {
  console.error(result.error);
}

​
Function Call Action

import { functionCall, teraGas } from '@near-api/universal';

const action = functionCall({
  functionName: 'my_method',
  functionArgs: { key: 'value' },
  gasLimit: { teraGas: '300' }
});

​
Common Gas Amounts

import { teraGas } from '@near-api/universal';

// Typical function call
const standardGas = teraGas('300');

// View function (minimal gas)
const viewGas = teraGas('30');

// Complex operation
const highGas = teraGas('300');

​
Validation

The library validates input:
  • Gas values: Must be non-negative bigint or integer number
    • Valid: 300000000000000n, 300000000000000
    • Invalid: 3.5, -100n
  • TerraGas values: Must be valid decimal strings with up to 12 decimal places
    • Valid: "300", "300.5", "0.000000000001"
    • Invalid: ".5", "300.", "1.5555555555555" (too many decimals)