Quick Start

This guide offers a simple example of how to use the @icp-sdk/core package to interact with Internet Computer canisters.

Using an Actor

This is the most common way to use the @icp-sdk/core package to interact with Internet Computer canisters.

index.ts

import { Actor, HttpAgent, type ActorSubclass } from "@icp-sdk/core/agent";
import { Ed25519KeyIdentity } from "@icp-sdk/core/identity";
import { Principal } from "@icp-sdk/core/principal";
import { idlFactory, type _SERVICE } from "./declarations";

const canisterId = Principal.fromText('uqqxf-5h777-77774-qaaaa-cai');
const identity = Ed25519KeyIdentity.generate();

const agent = await HttpAgent.create({
  host: 'https://icp-api.io',
  identity,
});

const actor = Actor.createActor(idlFactory, {
  canisterId,
  agent,
}) as ActorSubclass<_SERVICE>;

const response = await actor.greet('world');

console.log(response);

declarations.ts

// This file is typically auto-generated by the ICP CLI.

import type { ActorMethod } from '@icp-sdk/core/agent';
import type { IDL } from '@icp-sdk/core/candid';

export interface _SERVICE { 'greet' : ActorMethod<[string], string> }

export const idlFactory: IDL.InterfaceFactory = ({ IDL }) => {
    return IDL.Service({ 'greet' : IDL.Func([IDL.Text], [IDL.Text], []) });
};

Using the HttpAgent

You can also use the HttpAgent class to interact with canisters directly.

// Importing the HttpAgent from the agent module
import { HttpAgent } from '@icp-sdk/core/agent';
import { Ed25519KeyIdentity } from '@icp-sdk/core/identity';
import { IDL } from '@icp-sdk/core/candid';
import { Principal } from '@icp-sdk/core/principal';

const identity = Ed25519KeyIdentity.generate();
const canisterId = Principal.fromText('uqqxf-5h777-77774-qaaaa-cai');

const agent = await HttpAgent.create({
  host: 'https://icp-api.io',
  identity,
});

// Send an update call to the canister
await agent.call(canisterId, {
  methodName: 'greet',
  arg: IDL.encode([IDL.Text], ['world']),
});

Usage in a TypeScript project

If you are using TypeScript, have a look at the TypeScript guide.

Next Steps

Have a look at the Examples repo to see how to use the @icp-sdk/core package in a real-world application.