Class.KeybanClient

Main client for interacting with the Keyban API and associated services. This class provides methods to initialize accounts, retrieve balances, query NFTs, and interact with the Keyban blockchain.

Remarks

The KeybanClient serves as the primary interface for developers to interact with the Keyban ecosystem. It handles authentication, communication with the Keyban API, and provides utility methods for common tasks.

Example

// Initialize the client
const client = new KeybanClient({
  apiUrl: "https://api.keyban.io",
  appId: "your-app-id",
  accessTokenProvider: () => "your-access-token",
  chain: KeybanChain.KeybanTestnet,
});

// Initialize an account
const account = await client.initialize();

// Get balance
const balance = await client.getBalance(account.address);
console.log(`Balance: ${balance}`);

See

KeybanAccount

Constructors

new KeybanClient()

new KeybanClient(config: KeybanClientConfig): KeybanClient

Creates a new instance of KeybanClient.

Parameters

Parameter	Type	Description
config	KeybanClientConfig	The configuration object to initialize the client.

Returns

KeybanClient

Throws

If the configuration is invalid.

Example

const client = new KeybanClient({
  apiUrl: "https://api.keyban.io",
  appId: "your-app-id",
  accessTokenProvider: () => "your-access-token",
  clientShareKeyProvider: () => "your-client-shares-encryption-key-provider",
  chain: KeybanChain.KeybanTestnet,
});

Properties

Property	Type	Description
apiUrl	string	The Keyban API URL, defaulting to "https://api.keyban.io".
apolloClient	ApolloClient<NormalizedCacheObject>	The Apollo GraphQL client used for making API requests.
appId	string	The application ID used for authentication with the Keyban API.
chain	KeybanChain	The blockchain used by Keyban.
feesUnit	FeesUnit	The unit used for fees on the selected blockchain.
nativeCurrency	{ decimals: number; name: string; symbol: string; }	Represents the native currency of a blockchain network. Examples const nativeCurrency = { name: "Ether", symbol: "ETH", decimals: 18 }; const nativeCurrency = { name: "Bitcoin", symbol: "BTC", decimals: 8 };
nativeCurrency.decimals	number	-
nativeCurrency.name	string	-
nativeCurrency.symbol	string	-

Methods

apiStatus()

apiStatus(): Promise<KeybanApiStatus>

Performs a health check on the Keyban API to determine its operational status.

Returns

Promise<KeybanApiStatus>

A promise resolving to the API status, either "operational" or "down".

Example

const status = await client.apiStatus();
console.log(`API Status: ${status}`);

Throws

Throws an error if the health check request fails.

See

KeybanApiStatus

---

getBalance()

getBalance(address: `0x${string}`): Promise<string>

Retrieves the native token balance for a given address.

Parameters

Parameter	Type	Description
address	`0x${string}`	The Ethereum address for which to retrieve the balance.

Returns

Promise<string>

A promise resolving to the balance as a string (representing a BigInt in wei).

Throws

Throws SdkErrorTypes.AddressInvalid if the provided address is invalid.

Example

const balance = await client.getBalance("0x123...");
console.log(`Balance: ${balance}`);

Deprecated

---

getNft()

getNft(
   address: `0x${string}`, 
   tokenAddress: `0x${string}`, 
   tokenId: string): Promise<{
  balance: string;
  id: string;
  nft: null | {
     collection: null | {
        decimals: null | number;
        iconUrl: null | string;
        id: string;
        name: null | string;
        symbol: null | string;
        type: string;
       };
     id: string;
     metadata: any;
     tokenId: string;
    };
}>

Retrieves a specific NFT (ERC721 or ERC1155) owned by an address.

Parameters

Parameter	Type	Description
address	`0x${string}`	The Ethereum address of the owner.
tokenAddress	`0x${string}`	The contract address of the NFT.
tokenId	string	The token ID of the NFT.

Returns

Promise<{ balance: string; id: string; nft: null | { collection: null | { decimals: null | number; iconUrl: null | string; id: string; name: null | string; symbol: null | string; type: string; }; id: string; metadata: any; tokenId: string; }; }>

A promise resolving to the NFT data, including metadata and collection details.

Name	Type
balance	string
id	string
nft	null | { collection: null | { decimals: null | number; iconUrl: null | string; id: string; name: null | string; symbol: null | string; type: string; }; id: string; metadata: any; tokenId: string; }

Throws

Throws SdkErrorTypes.AddressInvalid if the provided addresses are invalid.

Throws

Throws SdkErrorTypes.NftNotFound if the NFT is not found.

Example

const nft = await client.getNft("0xowner...", "0xcontract...", "1");
console.log(nft);

Deprecated

---

getNfts()

getNfts(address: `0x${string}`, pagination?: PaginationArgs): Promise<null | {
  edges: {
     cursor: null | string;
     node: null | {
        balance: string;
        id: string;
        nft: null | {
           collection: null | {
              decimals: ...;
              iconUrl: ...;
              id: ...;
              name: ...;
              symbol: ...;
              type: ...;
             };
           id: string;
           metadata: any;
           tokenId: string;
          };
       };
    }[];
  pageInfo: {
     endCursor: null | string;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     startCursor: null | string;
    };
  totalCount: number;
}>

Retrieves the NFTs (ERC721 and ERC1155 tokens) owned by a given address.

Parameters

Parameter	Type	Description
address	`0x${string}`	The Ethereum address of the owner.
pagination?	PaginationArgs	Optional pagination arguments.

Returns

Promise<null | { edges: { cursor: null | string; node: null | { balance: string; id: string; nft: null | { collection: null | { decimals: ...; iconUrl: ...; id: ...; name: ...; symbol: ...; type: ...; }; id: string; metadata: any; tokenId: string; }; }; }[]; pageInfo: { endCursor: null | string; hasNextPage: boolean; hasPreviousPage: boolean; startCursor: null | string; }; totalCount: number; }>

A promise resolving to the list of NFTs, including metadata and collection details.

Throws

Throws SdkErrorTypes.AddressInvalid if the provided address is invalid.

Example

const nfts = await client.getNfts("0x123...", { first: 5 });
console.log(nfts);

See

PaginationArgs

Deprecated

---

getTokenBalances()

getTokenBalances(address: `0x${string}`, pagination?: PaginationArgs): Promise<null | {
  edges: {
     cursor: null | string;
     node: null | {
        balance: string;
        id: string;
        token: null | {
           decimals: null | number;
           iconUrl: null | string;
           id: string;
           name: null | string;
           symbol: null | string;
           type: string;
          };
       };
    }[];
  pageInfo: {
     endCursor: null | string;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     startCursor: null | string;
    };
  totalCount: number;
}>

Retrieves the ERC20 token balances for a given address.

Parameters

Parameter	Type	Description
address	`0x${string}`	The Ethereum address for which to retrieve the token balances.
pagination?	PaginationArgs	Optional pagination arguments.

Returns

Promise<null | { edges: { cursor: null | string; node: null | { balance: string; id: string; token: null | { decimals: null | number; iconUrl: null | string; id: string; name: null | string; symbol: null | string; type: string; }; }; }[]; pageInfo: { endCursor: null | string; hasNextPage: boolean; hasPreviousPage: boolean; startCursor: null | string; }; totalCount: number; }>

A promise resolving to the token balances, including token details and balances.

Throws

Throws SdkErrorTypes.AddressInvalid if the provided address is invalid.

Example

const tokenBalances = await client.getTokenBalances("0x123...", { first: 10 });
console.log(tokenBalances);

See

PaginationArgs

Deprecated

---

getTransferHistory()

getTransferHistory(address: `0x${string}`, pagination?: PaginationArgs): Promise<null | {
  edges: {
     cursor: null | string;
     node: null | {
        decimals: null | number;
        from: null | {
           id: string;
          };
        id: string;
        nft: null | {
           collection: null | {
              decimals: ...;
              iconUrl: ...;
              id: ...;
              name: ...;
              symbol: ...;
              type: ...;
             };
           id: string;
           metadata: any;
           tokenId: string;
          };
        to: null | {
           id: string;
          };
        token: null | {
           decimals: null | number;
           iconUrl: null | string;
           id: string;
           name: null | string;
           symbol: null | string;
           type: string;
          };
        transaction: null | {
           blockHash: string;
           blockNumber: string;
           date: string;
           fees: string;
           gasPrice: string;
           gasUsed: string;
           id: string;
           success: boolean;
          };
        type: string;
        value: string;
       };
    }[];
  pageInfo: {
     endCursor: null | string;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     startCursor: null | string;
    };
  totalCount: number;
}>

Retrieves the transaction history for a given address, including native currency transfers, token transfers, and NFT transfers.

Parameters

Parameter	Type	Description
address	`0x${string}`	The Ethereum address for which to retrieve the transaction history.
pagination?	PaginationArgs	Optional pagination arguments.

Returns

Promise<null | { edges: { cursor: null | string; node: null | { decimals: null | number; from: null | { id: string; }; id: string; nft: null | { collection: null | { decimals: ...; iconUrl: ...; id: ...; name: ...; symbol: ...; type: ...; }; id: string; metadata: any; tokenId: string; }; to: null | { id: string; }; token: null | { decimals: null | number; iconUrl: null | string; id: string; name: null | string; symbol: null | string; type: string; }; transaction: null | { blockHash: string; blockNumber: string; date: string; fees: string; gasPrice: string; gasUsed: string; id: string; success: boolean; }; type: string; value: string; }; }[]; pageInfo: { endCursor: null | string; hasNextPage: boolean; hasPreviousPage: boolean; startCursor: null | string; }; totalCount: number; }>

A promise resolving to the transaction history, including detailed information about each transfer.

Throws

Throws SdkErrorTypes.AddressInvalid if the provided address is invalid.

Example

const history = await client.getTransferHistory("0x123...", { first: 10 });
console.log(history);

See

PaginationArgs

Deprecated

---

initialize()

initialize(): Promise<KeybanAccount>

Initializes a KeybanAccount associated with the current client. This method sets up the account by retrieving or generating the client share, and prepares the account for transactions and other operations.

Returns

Promise<KeybanAccount>

A promise that resolves to an instance of KeybanAccount.

Throws

If initialization fails due to signing errors.

Example

const account = await client.initialize();
console.log(`Account address: ${account.address}`);

See

KeybanAccount