> For the complete documentation index, see [llms.txt](https://onegate.gitbook.io/onegate/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onegate.gitbook.io/onegate/nep-21-dapi-for-n3/api-reference.md).

# API Reference

This page documents the `IDapiProvider` interface defined by the current NEP-21 proposal.

## Provider

### `Neo.DapiProvider.ready`

Wallet providers dispatch this browser event when an `IDapiProvider` is ready. dApps listen for it and read the provider from `event.detail.provider`.

| Field             | Type            | Description                              |
| ----------------- | --------------- | ---------------------------------------- |
| `detail.provider` | `IDapiProvider` | Provider instance exposed by the wallet. |

```ts
window.addEventListener("Neo.DapiProvider.ready", (event) => {
  const provider = (event as CustomEvent).detail.provider;
});
```

### `Neo.DapiProvider.request`

dApps may dispatch this browser event to request a provider.

| Field            | Type      | Description                         |
| ---------------- | --------- | ----------------------------------- |
| `detail.version` | `Version` | dAPI version requested by the dApp. |

```ts
window.dispatchEvent(new CustomEvent("Neo.DapiProvider.request", {
  detail: {
    version: "1.0",
  },
}));
```

If multiple providers respond, the dApp may choose which provider to use.

### Provider properties

NEP-21 exposes provider information as properties on the provider object.

| Property            | Type        | Description                                                       |
| ------------------- | ----------- | ----------------------------------------------------------------- |
| `name`              | `string`    | Provider name.                                                    |
| `version`           | `Version`   | Provider version.                                                 |
| `dapiVersion`       | `Version`   | dAPI version. It must currently be `"1.0"`.                       |
| `compatibility`     | `string[]`  | Supported standards. It should include `"NEP-21"` when supported. |
| `connected`         | `boolean`   | Whether the user has connected their wallet to the dApp.          |
| `network`           | `Network`   | Current network.                                                  |
| `supportedNetworks` | `Network[]` | Networks supported by the provider.                               |
| `icon`              | `string`    | Provider icon URL. The URL scheme should be `https` or `data`.    |
| `website`           | `string`    | Provider website.                                                 |
| `extra`             | `any`       | Additional provider data.                                         |

```ts
console.log(provider.name);
console.log(provider.compatibility);
console.log(provider.network);
```

Example provider information:

```json
{
  "name": "Example Wallet",
  "version": "1.0.0",
  "dapiVersion": "1.0",
  "compatibility": ["NEP-21"],
  "connected": true,
  "network": 894710606,
  "supportedNetworks": [860833102, 894710606],
  "icon": "https://wallet.example/icon.png",
  "website": "https://wallet.example",
  "extra": {}
}
```

## Account and Authentication

### `authenticate(payload)`

Requests authentication. This is usually used to log in to a website. The authentication process is described in NEP-20.

| Parameter | Type                             | Description                       |
| --------- | -------------------------------- | --------------------------------- |
| `payload` | `AuthenticationChallengePayload` | Authentication challenge payload. |

Returns `AuthenticationResponsePayload`.

Possible errors: `UNSUPPORTED`, `INVALID`, `TIMEOUT`, `CANCELED`.

```ts
const result = await provider.authenticate({
  action: "Authentication",
  grant_type: "Signature",
  allowed_algorithms: ["ECDSA-P256"],
  domain: "example.com",
  networks: [894710606],
  nonce: "nonce-value",
  timestamp: Date.now(),
});
```

Example response:

```json
{
  "algorithm": "ECDSA-P256",
  "network": 894710606,
  "pubkey": "03b209fd4f53a7170ea4444e0cb0a6bb6a53c2bd016926989cf85f9b0fba17a70c",
  "address": "NSiVJYZej4XsxG5CUpdwn7VRQk8iiiDMPM",
  "nonce": "nonce-value",
  "timestamp": 1710000000000,
  "signature": "base64-signature"
}
```

### `getAccounts()`

Gets the current connected account in the wallet.

Parameters: none.

Returns `Account[]`.

```ts
const accounts = await provider.getAccounts();
```

Example response:

```json
[
  {
    "hash": "0x682cca3ebdc66210e5847d7f8115846586079d4a",
    "address": "NSiVJYZej4XsxG5CUpdwn7VRQk8iiiDMPM",
    "label": "Account 1"
  }
]
```

### `pickAddress(prompt?)`

Prompts the user to select an account from the wallet and returns the selected address.

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `prompt`  | `string` | Optional prompt shown to the user. |

Returns `Address`.

Possible error: `CANCELED`.

```ts
const address = await provider.pickAddress("Select an address");
```

## Read Methods

### `getBalance(asset, account)`

Gets the balance of the specified account. The account can be in the wallet or an arbitrary address.

| Parameter | Type      | Description          |
| --------- | --------- | -------------------- |
| `asset`   | `UInt160` | Asset contract hash. |
| `account` | `UInt160` | Account script hash. |

Returns `Integer`.

Possible errors: `INVALID`, `NOTFOUND`, `FAILED`, `RPC_ERROR`.

```ts
const balance = await provider.getBalance(
  "0xd2a4cff31913016155e38e474a2c06d08be276cf",
  "0x682cca3ebdc66210e5847d7f8115846586079d4a",
);
```

### `getTokenInfo(hash)`

Gets information about a token.

| Parameter | Type      | Description          |
| --------- | --------- | -------------------- |
| `hash`    | `UInt160` | Token contract hash. |

Returns `Token`.

Possible errors: `INVALID`, `NOTFOUND`, `FAILED`, `RPC_ERROR`.

```ts
const token = await provider.getTokenInfo("0xd2a4cff31913016155e38e474a2c06d08be276cf");
```

### `call(invocation)`

Calls a contract offchain and returns the execution result.

| Parameter    | Type                  | Description              |
| ------------ | --------------------- | ------------------------ |
| `invocation` | `InvocationArguments` | Contract call arguments. |

Returns `InvocationResult`.

Possible errors: `INVALID`, `RPC_ERROR`.

```ts
const result = await provider.call({
  hash: "0xd2a4cff31913016155e38e474a2c06d08be276cf",
  operation: "symbol",
  args: [],
});
```

### `getBlock(hash)`

Gets a block by hash.

| Parameter | Type      | Description |
| --------- | --------- | ----------- |
| `hash`    | `UInt256` | Block hash. |

Returns `Block`.

Possible errors: `INVALID`, `NOTFOUND`, `RPC_ERROR`.

```ts
const block = await provider.getBlock("0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
```

### `getBlock(index)`

Gets a block by index.

| Parameter | Type     | Description  |
| --------- | -------- | ------------ |
| `index`   | `number` | Block index. |

Returns `Block`.

Possible errors: `INVALID`, `NOTFOUND`, `RPC_ERROR`.

```ts
const block = await provider.getBlock(1000);
```

### `getBlockCount()`

Gets the count of blocks in the blockchain.

Parameters: none.

Returns `number`.

Possible error: `RPC_ERROR`.

```ts
const count = await provider.getBlockCount();
```

### `getTransaction(txid)`

Gets a transaction by hash.

| Parameter | Type      | Description       |
| --------- | --------- | ----------------- |
| `txid`    | `UInt256` | Transaction hash. |

Returns `Transaction`.

Possible errors: `INVALID`, `NOTFOUND`, `RPC_ERROR`.

```ts
const tx = await provider.getTransaction("0x1f4d1defa46faa5e7b9b8d3f79a06bec777d7c26c4aa5f6f5899a291daa87c15");
```

### `getApplicationLog(txid)`

Gets the application log of a transaction.

| Parameter | Type      | Description       |
| --------- | --------- | ----------------- |
| `txid`    | `UInt256` | Transaction hash. |

Returns `ApplicationLog`.

Possible errors: `INVALID`, `RPC_ERROR`.

```ts
const log = await provider.getApplicationLog("0x1f4d1defa46faa5e7b9b8d3f79a06bec777d7c26c4aa5f6f5899a291daa87c15");
```

### `getStorage(hash, key)`

Gets a storage entry.

| Parameter | Type            | Description    |
| --------- | --------------- | -------------- |
| `hash`    | `UInt160`       | Contract hash. |
| `key`     | `Base64Encoded` | Storage key.   |

Returns `Base64Encoded`.

Possible errors: `INVALID`, `NOTFOUND`, `RPC_ERROR`.

```ts
const value = await provider.getStorage(
  "0x0123456789abcdef0123456789abcdef01234567",
  "dG9rZW4w",
);
```

## Write and Signing Methods

### `send(asset, from, to, amount, data?)`

Sends assets to an account and returns the transaction hash.

| Parameter | Type       | Description                    |
| --------- | ---------- | ------------------------------ |
| `asset`   | `UInt160`  | Asset contract hash.           |
| `from`    | `UInt160`  | Sender account script hash.    |
| `to`      | `UInt160`  | Recipient account script hash. |
| `amount`  | `Integer`  | Amount to send.                |
| `data`    | `Argument` | Optional transfer data.        |

Returns `UInt256`.

Possible errors: `INVALID`, `NOTFOUND`, `FAILED`, `TIMEOUT`, `CANCELED`, `INSUFFICIENT_FUNDS`, `RPC_ERROR`.

```ts
const txid = await provider.send(
  "0xd2a4cff31913016155e38e474a2c06d08be276cf",
  "0x682cca3ebdc66210e5847d7f8115846586079d4a",
  "0x1111111111111111111111111111111111111111",
  "100000000",
  { type: "Any" },
);
```

### `invoke(invocations, signers?, attributes?, options?)`

Calls one or more contracts onchain and returns the transaction hash.

| Parameter     | Type                     | Description                      |
| ------------- | ------------------------ | -------------------------------- |
| `invocations` | `InvocationArguments[]`  | Contract calls.                  |
| `signers`     | `Signer[]`               | Optional transaction signers.    |
| `attributes`  | `TransactionAttribute[]` | Optional transaction attributes. |
| `options`     | `TransactionOptions`     | Optional transaction options.    |

Returns `UInt256`.

Possible errors: `INVALID`, `FAILED`, `TIMEOUT`, `CANCELED`, `RPC_ERROR`.

```ts
const txid = await provider.invoke([
  {
    hash: "0xd2a4cff31913016155e38e474a2c06d08be276cf",
    operation: "transfer",
    args: [
      { type: "Hash160", value: "0x682cca3ebdc66210e5847d7f8115846586079d4a" },
      { type: "Hash160", value: "0x1111111111111111111111111111111111111111" },
      { type: "Integer", value: "100000000" },
      { type: "Any" }
    ],
    abortOnFail: true
  }
]);
```

### `makeTransaction(invocations, signers?, attributes?, options?)`

Calls one or more contracts onchain and returns the transaction without relaying it.

| Parameter     | Type                     | Description                      |
| ------------- | ------------------------ | -------------------------------- |
| `invocations` | `InvocationArguments[]`  | Contract calls.                  |
| `signers`     | `Signer[]`               | Optional transaction signers.    |
| `attributes`  | `TransactionAttribute[]` | Optional transaction attributes. |
| `options`     | `TransactionOptions`     | Optional transaction options.    |

Returns `ContractParametersContext`.

Possible errors: `INVALID`, `FAILED`, `TIMEOUT`, `CANCELED`, `RPC_ERROR`.

```ts
const context = await provider.makeTransaction(
  [
    {
      hash: "0xd2a4cff31913016155e38e474a2c06d08be276cf",
      operation: "transfer",
      args: [
        { type: "Hash160", value: "0x682cca3ebdc66210e5847d7f8115846586079d4a" },
        { type: "Hash160", value: "0x1111111111111111111111111111111111111111" },
        { type: "Integer", value: "100000000" },
        { type: "Any" }
      ],
      abortOnFail: true
    }
  ],
  [
    {
      account: "0x682cca3ebdc66210e5847d7f8115846586079d4a",
      scopes: "CalledByEntry"
    }
  ]
);
```

### `sign(context)`

Signs a transaction with the current wallet. This is usually used for multi-signature transactions.

| Parameter | Type                        | Description          |
| --------- | --------------------------- | -------------------- |
| `context` | `ContractParametersContext` | Transaction context. |

Returns `ContractParametersContext`.

Possible errors: `UNSUPPORTED`, `INVALID`, `NOTFOUND`, `TIMEOUT`, `CANCELED`.

```ts
// context is a ContractParametersContext returned by makeTransaction.
const signedContext = await provider.sign(context);
```

### `signMessage(message, account?, options?)`

Signs a message with the specified account. The algorithm is ECDSA with SHA-256.

| Parameter | Type                      | Description                   |
| --------- | ------------------------- | ----------------------------- |
| `message` | `string \| Base64Encoded` | Message to sign.              |
| `account` | `UInt160`                 | Optional account script hash. |
| `options` | `SignOptions`             | Optional signing options.     |

Returns `SignedMessage`.

Possible errors: `INVALID`, `NOTFOUND`, `TIMEOUT`, `CANCELED`.

```ts
const signed = await provider.signMessage(
  "hello",
  "0x682cca3ebdc66210e5847d7f8115846586079d4a",
  { isBase64Encoded: false },
);
```

### `relay(context)`

Relays a transaction and returns the transaction hash.

| Parameter | Type                        | Description          |
| --------- | --------------------------- | -------------------- |
| `context` | `ContractParametersContext` | Transaction context. |

Returns `UInt256`.

Possible errors: `INVALID`, `TIMEOUT`, `CANCELED`, `INSUFFICIENT_FUNDS`, `RPC_ERROR`.

```ts
// signedContext is a signed ContractParametersContext.
const txid = await provider.relay(signedContext);
```

## Event Methods

### `on(event, listener)`

Adds an event handler.

| Parameter  | Type                       | Description                               |
| ---------- | -------------------------- | ----------------------------------------- |
| `event`    | `EventName`                | `"accountchanged"` or `"networkchanged"`. |
| `listener` | `(e: CustomEvent) => void` | Event handler.                            |

```ts
provider.on("accountchanged", (event) => {
  console.log(event.detail.accounts);
});
```

### `removeListener(event, listener)`

Removes an event handler.

| Parameter  | Type                       | Description                               |
| ---------- | -------------------------- | ----------------------------------------- |
| `event`    | `EventName`                | `"accountchanged"` or `"networkchanged"`. |
| `listener` | `(e: CustomEvent) => void` | Event handler to remove.                  |

```ts
const onAccountChanged = (event: CustomEvent) => {
  console.log(event.detail.accounts);
};

provider.on("accountchanged", onAccountChanged);
provider.removeListener("accountchanged", onAccountChanged);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://onegate.gitbook.io/onegate/nep-21-dapi-for-n3/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.