Documentation Index
Fetch the complete documentation index at: https://mintlify.com/near/near-api-ts/llms.txt
Use this file to discover all available pages before exploring further.
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"
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"
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' });
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"
safeAdd()
sub()
Subtract gas amounts.
const gas1 = teraGas('100');
const gas2 = teraGas('30');
const result = gas1.sub(gas2);
console.log(result.teraGas); // "70"
safeSub()
gt()
Compare if greater than.
const gas1 = teraGas('100');
const gas2 = teraGas('50');
console.log(gas1.gt(gas2)); // true
safeGt()
lt()
Compare if less than.
const gas1 = teraGas('50');
const gas2 = teraGas('100');
console.log(gas1.lt(gas2)); // true
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)