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 { HttpAgent } from "@icp-sdk/core/agent";
import { Ed25519KeyIdentity } from "@icp-sdk/core/identity";
import { Principal } from "@icp-sdk/core/principal";
import { createActor } from "./api/hello-world";

// For a convenient way to get the canister ID,
// see the https://js.icp.build/core/latest/canister-environment/ guide.
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 = createActor(canisterId, {
  agent,
});

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

console.log(response);

api/hello-world.ts

// This file is typically auto-generated by the @icp-sdk/bindgen package.
// You should not write this file manually.
import { Actor, HttpAgent, type HttpAgentOptions, type ActorConfig, type Agent, type ActorSubclass } from "@icp-sdk/core/agent";
import { idlFactory, type _SERVICE } from "./declarations/hello-world.did";

// ... omitted for brevity ...

export class Hello_world implements hello_worldInterface {
    constructor(private actor: ActorSubclass<_SERVICE>){}
    async greet(arg0: string): Promise<string> {
        const result = await this.actor.greet(arg0);
        return result;
    }
}

// ... omitted for brevity ...

export function createActor(canisterId: string, options: CreateActorOptions = {}): Hello_world {
    // ... omitted for brevity ...
    return new Hello_world(actor);
}

To generate the bindings for your canister, you can use the @icp-sdk/bindgen package.

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();
// For a convenient way to get the canister ID,
// see the https://js.icp.build/core/latest/canister-environment/ guide.
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 Canister Environment guide for how to load the canister environment from the asset canister.
• Have a look at the @icp-sdk/bindgen package for how to generate the bindings for your canister.
• Have a look at the Examples repo to see how to use the @icp-sdk/core package in a real-world application.