Struct Tokens 

pub struct Tokens {
    account_id: AccountId,
}

A wrapper struct that simplifies interactions with NEAR, FT, NFT

This struct provides convenient methods to interact with different types of tokens on NEAR Protocol:

• Native NEAR token operations
• Fungible Token - Documentation and examples, NEP-141
• Non-Fungible Token - Documentation and examples, NEP-171

Examples

Fungible Token Operations

use near_api::*;

let bob_tokens = Tokens::account("bob.testnet".parse()?);

// Check FT balance
let balance = bob_tokens.ft_balance("usdt.tether-token.near".parse()?)?.fetch_from_mainnet().await?;
println!("Bob balance: {}", balance);

// Transfer FT tokens
bob_tokens.send_to("alice.testnet".parse()?)
    .ft(
        "usdt.tether-token.near".parse()?,
        USDT_BALANCE.with_whole_amount(100)
    )?
    .with_signer(Signer::new(Signer::from_ledger())?)
    .send_to_mainnet()
    .await?;

NFT Operations

use near_api::*;

let alice_tokens = Tokens::account("alice.testnet".parse()?);

// Check NFT assets
let tokens = alice_tokens.nft_assets("nft-contract.testnet".parse()?)?.fetch_from_testnet().await?;
println!("NFT count: {}", tokens.data.len());

// Transfer NFT
alice_tokens.send_to("bob.testnet".parse()?)
    .nft("nft-contract.testnet".parse()?, "token-id".to_string())?
    .with_signer(Signer::new(Signer::from_ledger())?)
    .send_to_testnet()
    .await?;

NEAR Token Operations

use near_api::*;

let alice_account = Tokens::account("alice.testnet".parse()?);

// Check NEAR balance
let balance = alice_account.near_balance().fetch_from_testnet().await?;
println!("NEAR balance: {}", balance.total);

// Send NEAR
alice_account.send_to("bob.testnet".parse()?)
    .near(NearToken::from_near(1))
    .with_signer(Signer::new(Signer::from_ledger())?)
    .send_to_testnet()
    .await?;

Fields

account_id: AccountId

Implementations

impl Tokens

pub const fn account(account_id: AccountId) -> Self

pub const fn account_id(&self) -> &AccountId

Returns the underlying account ID for this tokens wrapper.

Example

use near_api::*;

let tokens = Tokens::account("alice.testnet".parse()?);
let account_id = tokens.account_id();
println!("Account ID: {}", account_id);

pub fn as_account(&self) -> Account

Converts this tokens wrapper to an Account for account-related operations.

Example

use near_api::*;

let tokens = Tokens::account("alice.testnet".parse()?);
let account = tokens.as_account();
let account_info = account.view().fetch_from_testnet().await?;
println!("Account info: {:?}", account_info);

pub fn near_balance( &self, ) -> RequestBuilder<PostprocessHandler<UserBalance, AccountViewHandler>>

Fetches the total NEAR balance (UserBalance) of the account.

Example

use near_api::*;

let alice_tokens = Tokens::account("alice.testnet".parse()?);
let balance = alice_tokens.near_balance().fetch_from_testnet().await?;
println!("Alice's NEAR balance: {:?}", balance);

pub fn nft_metadata( contract_id: AccountId, ) -> Result<RequestBuilder<CallResultHandler<NFTContractMetadata>>, BuilderError>

Prepares a new contract query (nft_metadata) for fetching the NFT metadata (NFTContractMetadata).

The function depends that the contract implements NEP-171

Example

use near_api::*;

let metadata = Tokens::nft_metadata("nft-contract.testnet".parse()?)?
    .fetch_from_testnet()
    .await?;
println!("NFT metadata: {:?}", metadata);

pub fn nft_assets( &self, nft_contract: AccountId, ) -> Result<RequestBuilder<CallResultHandler<Vec<Token>>>, BuilderError>

Prepares a new contract query (nft_tokens_for_owner) for fetching the NFT assets of the account (Vec<Token>).

The function depends that the contract implements NEP-171

Example

use near_api::*;

let alice_tokens = Tokens::account("alice.testnet".parse()?);
let alice_assets = alice_tokens.nft_assets("nft-contract.testnet".parse()?)?
    .fetch_from_testnet()
    .await?;
println!("Alice's NFT assets: {:?}", alice_assets);

pub fn ft_metadata( contract_id: AccountId, ) -> Result<RequestBuilder<CallResultHandler<FungibleTokenMetadata>>, BuilderError>

Prepares a new contract query (ft_metadata) for fetching the FT metadata (FungibleTokenMetadata).

The function depends that the contract implements NEP-141

Example

use near_api::*;

let metadata = Tokens::ft_metadata("usdt.tether-token.near".parse()?)?
    .fetch_from_testnet()
    .await?
    .data;
println!("FT metadata: {} {}", metadata.name, metadata.symbol);

pub fn ft_balance( &self, ft_contract: AccountId, ) -> Result<MultiRequestBuilder<PostprocessHandler<FTBalance, MultiQueryHandler<(CallResultHandler<FungibleTokenMetadata>, CallResultHandler<U128>)>>>, BuilderError>

Prepares a new contract query (ft_balance_of, ft_metadata) for fetching the FTBalance of the account.

This query is a multi-query, meaning it will fetch the FT metadata and the FT balance of the account. The result is then postprocessed to create a FTBalance instance.

The function depends that the contract implements NEP-141

Example

use near_api::*;

let alice_usdt_balance = Tokens::account("alice.near".parse()?)
    .ft_balance("usdt.tether-token.near".parse()?)?
    .fetch_from_mainnet()
    .await?;
println!("Alice's USDT balance: {}", alice_usdt_balance);

pub fn send_to(&self, receiver_id: AccountId) -> SendToBuilder

Prepares a new transaction builder for sending tokens to another account.

This builder is used to construct transactions for sending NEAR, FT, and NFT tokens.

Sending NEAR

use near_api::*;

let alice_tokens = Tokens::account("alice.near".parse()?);

let result = alice_tokens.send_to("bob.near".parse()?)
    .near(NearToken::from_near(1))
    .with_signer(Signer::new(Signer::from_ledger())?)
    .send_to_mainnet()
    .await?;

Sending FT

use near_api::*;

let alice_tokens = Tokens::account("alice.near".parse()?);

let result = alice_tokens.send_to("bob.near".parse()?)
    .ft("usdt.tether-token.near".parse()?, USDT_BALANCE.with_whole_amount(100))?
    .with_signer(Signer::new(Signer::from_ledger())?)
    .send_to_mainnet()
    .await?;

Sending NFT

use near_api::*;

let alice_tokens = Tokens::account("alice.near".parse()?);

let result = alice_tokens.send_to("bob.near".parse()?)
    .nft("nft-contract.testnet".parse()?, "token-id".to_string())?
    .with_signer(Signer::new(Signer::from_ledger())?)
    .send_to_testnet()
    .await?;

Trait Implementations

impl Clone for Tokens

fn clone(&self) -> Tokens

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Tokens

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.