> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hex-api.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Intents

> The Intents builder: transfers, token diffs, withdrawals and payments, signed by a wallet and published to the solver relay.

The `Intents` builder composes NEAR Intents, has a wallet sign them and publishes them to the solver relay. Amounts can
be numbers (converted with the token's decimals) or `bigint` base units.

```ts theme={null}
const hash = await kit
  .intentsBuilder() // signer: kit.priorityWallet; asks the user to connect when there is none
  .transfer({ recipient: "merchant.near", token: OmniToken.USDC, amount: 5 })
  .execute();
```

On the server, or with an explicit signer:

```ts theme={null}
import { Intents, OmniToken } from "@hot-labs/kit/core";
import { NearWallet } from "@hot-labs/kit/near";

const wallet = NearWallet.fromPrivateKey(key, "my-account.near");
await Intents.builder(wallet).transfer({ recipient: "bob.near", token: OmniToken.USDT, amount: 1 }).execute();
```

## Building

| Method | Intent |
| - | - |
| `transfer({ recipient, token, amount, memo?, msg?, tgas? })` | Transfer inside NEAR Intents; with `msg` it calls the receiver contract |
| `batchTransfer({ recipient, tokens, memo?, msg? })` | Several tokens to one recipient |
| `withdraw({ token, amount, receiver, memo?, msg? })` | Withdraw from NEAR Intents to the token's chain |
| `give(token, amount)` / `take(token, amount)` | A `token_diff` intent: what you give and what you expect. It settles only against a matching counter-intent (a solver quote) |
| `tokenDiff({ [token]: amount })` | The same, raw (negative = give) |
| `authCall({ contractId, msg, attachNear, tgas })` | Call a contract with the signer's authority |
| `addPublicKey(key)` / `removePublicKey(key)` | Manage the signer's intents keys |
| `addRawIntent(intent)` | Any intent object |

Options for the signed commitment: `attachDeadline(date)`, `attachTimeout(seconds)`, `attachNonce(bytes)`,
`attachWallet(wallet)`, `attachSeed(seed)`.

## Signing and publishing

| Method | Does |
| - | - |
| `sign()` | Signs the pending intents, returns the commitment |
| `simulate()` | Signs if needed and dry-runs the commitments on the verifier contract |
| `execute({ onStep? })` | Signs if needed, publishes, waits for settlement; resolves with the transaction hash |
| `depositAndExecute(options)` | Browser only. Opens the Payment popup: the user picks what to pay with, the kit deposits or swaps the missing tokens into the HOT balance, then executes |

`depositAndExecute` takes `title`, `message`, `allowedTokens`, `excludedTokens`, `silent` and `onStep`. Steps are
`"payment" | "funds" | "signing" | "publishing" | "confirming"`.

```ts theme={null}
await kit
  .intentsBuilder()
  .transfer({ recipient: "pay.fi.tg", token: OmniToken.USDC, amount: 10, msg: JSON.stringify({ order: 42 }) })
  .depositAndExecute({ title: "Order #42", onStep: (step) => console.log(step) });
```

## Retries

When the publish times out after the intents were sent, `execute()` throws `SubmittedStatusUnknownError` and keeps the
signed commitments. Calling `execute()` again on the same builder checks the status first and republishes the same
commitments (same nonce, so they cannot settle twice). `discardUnknownOutcome()` drops them to start over. See
[Errors and waits](https://docs.hex-api.app/kit/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.