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

# Client SDK

> Every method on init() from @zendfi/appkit.

```bash theme={null}
npm install @zendfi/appkit
```

```ts theme={null}
import { init, ZendError } from "@zendfi/appkit";

const zend = init();
```

Every method returns a promise and rejects with `ZendError { code, message }`. Calls time out after 10 minutes, because money sheets can stay open while the user decides. See [Errors](https://developers.usezend.app/reference/errors.md).

## init(options?)

**zendOrigins** `string[]` (default: \["[https://app.usezend.app](https://app.usezend.app)"])

Zend web origins allowed to host your page. Add a staging origin while testing.

Returns the `zend` object below.

## zend.environment

`"zend-app"` (mobile WebView), `"zend-web"` (frame in `app.usezend.app`), or `"external"` (plain browser). In `external`, every call rejects with `NOT_IN_ZEND`.

## zend.launch

Read from the URL once, on load.

| Field | Set when |
| - | - |
| `interaction` | Opened from a chat action, a card button, or an `/i/<id>` link |
| `start` | A card's `start_interaction` button opened the app; the type to start |
| `from` | With `start`: the interaction whose card was tapped, to reuse its people |

## Identity

### identity.get()

Returns `{ appUserId, username, name, scopes, appSession }`. See [Sign in with Zend](https://developers.usezend.app/guides/identity.md).

## Money

### pay(params)

Send money to a Zend user. Needs `pay`. See [Take a payment](https://developers.usezend.app/money/pay.md).

```ts theme={null}
pay(p: {
  to: `@${string}`;
  note?: string;
  reference?: string;
  interactionId?: string;
  splits?: { to: "app" | `@${string}`; percent?: number; amount?: number }[];
} & ({ amount: number } | { price: { ngn: number } })): Promise<{ paymentId: string; status: string }>
```

### request(params)

Make an ask link others can pay. Needs `request_payment`. See [Ask links](https://developers.usezend.app/money/requests-and-links.md#ask-links).

```ts theme={null}
request(p: {
  amount?: number;
  price?: { ngn: number };
  note?: string;
  maxPayments?: number;
  reference?: string;
}): Promise<{ id: string; url: string }>
```

### createLink(params)

Make a money link. Zend shares it; you only get its id. Needs `create_link`. See [Money links](https://developers.usezend.app/money/requests-and-links.md#money-links).

```ts theme={null}
createLink(p: { uses?: number; note?: string; reference?: string }
  & ({ amount: number } | { price: { ngn: number } })): Promise<{ id: string; status: string }>
```

### allowance.request(params?) / allowance.get()

Ask for, or read, a spend allowance. See [Spend allowance](https://developers.usezend.app/money/allowance.md).

```ts theme={null}
allowance.request(p?: { perPayment?: { ngn: number }; perDay?: { ngn: number } }): Promise<Allowance | null>
allowance.get(): Promise<Allowance | null>
```

### prize.create / join / cancel / get

Host-funded prizes. Needs `prize`. See [Prizes](https://developers.usezend.app/money/prizes.md).

```ts theme={null}
prize.create(p: {
  joinInSecs: number; resolveInSecs: number; maxPlayers: number;
  disputeSecs?: number; reference?: string; interactionId?: string;
} & ({ amount: number } | { price: { ngn: number } })): Promise<Prize>
prize.join(id: string): Promise<Prize>
prize.cancel(id: string): Promise<Prize>
prize.get(id: string): Promise<Prize>
```

## Interactions

See [Interactions](https://developers.usezend.app/guides/interactions.md).

### interaction.create(params)

```ts theme={null}
interaction.create(p: {
  type: string;
  participants?: string[];      // @username, zu_..., or a pick token
  data?: Record<string, unknown>;
  visibility?: "participants" | "friends" | "public";
  expiresInSecs?: number;
  reuseOpen?: boolean;
}): Promise<Interaction>
```

### interaction.get(id)

```ts theme={null}
interaction.get(id: string): Promise<Interaction>
```

### interaction.update(id, params)

```ts theme={null}
interaction.update(id: string, p: {
  state: string;
  data?: Record<string, unknown>;
  idempotencyKey: string;
  expectedVersion?: number;
}): Promise<Interaction>
```

## Cards

### postCard(params)

Needs `post_card` and the user's consent to post. See [Cards](https://developers.usezend.app/guides/cards.md).

```ts theme={null}
postCard(p: {
  interactionId: string;
  template: "result" | "invite" | "status";
  placement: "chat" | "feed";
  idempotencyKey: string;
  slots: {
    title: string;
    subtitle?: string;
    emoji?: string;
    media?: string;
    check?: boolean;
    buttons?: (
      | { label: string; action: "open_sheet"; path: string }
      | { label: string; action: "start_interaction"; type: string }
      | { label: string; action: "open_url"; url: string }
    )[];
  };
}): Promise<unknown>
```

## Realtime

### live.join(interactionId)

Join the interaction's live room. See [Live rooms](https://developers.usezend.app/guides/live-rooms.md).

```ts theme={null}
live.join(interactionId: string): Promise<LiveRoom>

interface LiveRoom {
  send(data: unknown): Promise<void>;
  on(event: "message", fn: (m: { from: string; data: unknown; at: string }) => void): () => void;
  on(event: "presence", fn: (members: LiveMember[]) => void): () => void;
  on(event: "closed", fn: (reason: string) => void): () => void;
  on(event: "status", fn: (status: "connected" | "reconnecting" | "disconnected") => void): () => void;
  leave(): Promise<void>;
}
```

## People

### people.pick(params?)

Open Zend's friend picker. See [People picker](https://developers.usezend.app/guides/people-picker.md).

```ts theme={null}
people.pick(p?: { max?: number; title?: string }): Promise<PickedPerson[]>
```

## Fair results

### random(params)

A draw nobody can rig. See [Random draws](https://developers.usezend.app/fairness/random-draws.md).

```ts theme={null}
random(p: { interactionId: string; label: string } & (
  | { kind: "int"; n: number }
  | { kind: "shuffle"; n: number }
  | { kind: "pick"; n: number; k: number }
)): Promise<RandomResult>
```

### attest(params)

Record a hash with Zend. Needs `attest`. See [Attestations](https://developers.usezend.app/fairness/attestations.md).

```ts theme={null}
attest(p: { label: string; dataHash: string; interactionId?: string }): Promise<AttestReceipt>
```

## App

### report(params)

Let the user report something in your app to Zend.

```ts theme={null}
report(p: {
  reason: "scam" | "unfair_result" | "offensive" | "broken" | "other";
  detail?: string;
  interactionId?: string;
  prizeId?: string;
}): Promise<void>
```

### close(result?)

Close your app. `result` goes back to whatever opened it inside Zend.

```ts theme={null}
close(result?: unknown): Promise<void>
```


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