> For the complete documentation index, see [llms.txt](https://bify.gitbook.io/rwa-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bify.gitbook.io/rwa-docs/bify-sdk/reference.md).

# BIFY SDK Reference

## Server component

```ts
const bify = new BifyClient({
  apiKey: process.env.BIFY_API_KEY!,
  baseUrl: process.env.BIFY_API_BASE_URL,
  network: "base-sepolia",
});
```

| Surface      | Methods                                                                     |
| ------------ | --------------------------------------------------------------------------- |
| Checkout     | `createOrderSession`, `retrieve`, `confirmHosted`, `claimHostedCertificate` |
| Orders       | `retrieve`, `markFulfilled`                                                 |
| Certificates | `retrieve`, `verify`, `list`, `confirmMint`                                 |
| Rewards      | `create`, `retrieve`, `claim`, `confirmClaim`, `retrieveClaim`              |
| Access       | `create`, `retrieve`, `setActive`, `grant`, `revoke`                        |
| Voting       | `createPoll`, `retrievePoll`, `setPollActive`                               |
| Identity     | `attest`                                                                    |
| Webhooks     | `verify`                                                                    |

## Identity attestation

Identity attestation is an optional server-to-server integration for partners that operate a verified identity provider. The signature is sent in the `BIFY-KYC-Signature` header; the provider secret is never sent in the JSON body.

```ts
const providerTimestamp = providerEvent.timestamp;
const providerSignature = providerEvent.signature;

const attestation = await bify.identity.attest({
  walletAddress: "0x1234567890123456789012345678901234567890",
  eventId: "provider-event-123",
  occurredAt: Math.floor(Date.now() / 1000),
  kycStatus: 1,
  jurisdiction: "0x7777777777777777777777777777777777777777777777777777777777777777",
  kycExpiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 365,
  geoAllowed: true,
  // These values come from the trusted identity provider integration.
  signature: `t=${providerTimestamp},v1=${providerSignature}`,
});
```

Call this from a trusted provider integration or partner backend. Do not allow an unauthenticated browser to choose `kycStatus` or `geoAllowed`.

## Browser component

```ts
import {
  mountBifyHostedCheckout,
  mountBifyCertificate,
  mountBifyRewardClaim,
} from "@bify/commerce-widget";
```

The browser component never receives the partner API key or webhook secret.

## Checkout widget options

```ts
type BifyHostedCheckoutOptions = {
  element: HTMLElement | string;
  apiBaseUrl: string;
  sessionId: string;
  clientToken: string;
  theme?: "light" | "dark";
  themeToggle?: boolean;
  openOnMount?: boolean;
  shippingRequired?: boolean;
  customer?: {
    name?: string;
    email?: string;
    phone?: string;
  };
  onState?: (state: string, message: string) => void;
  onComplete?: (details: {
    session: unknown;
    transactionHash: string;
    certificate: unknown;
  }) => void;
};
```

For a preloaded session, use `mountBifyCommerce`. For the normal partner integration, use `mountBifyHostedCheckout` and pass only the session ID and client token to the browser.

## Contract-backed browser helpers

```ts
import {
  castVote,
  checkAccess,
  checkVote,
  ensureChain,
  readVotes,
  requestAccounts,
} from "@bify/commerce-widget";
```

Use `mountBifyCertificate` and `mountBifyRewardClaim` for signed voucher transactions. Use the access and voting helpers for direct reads and wallet transactions. The helpers use the browser's EIP-1193 provider and do not receive partner API credentials.

## Contract-to-SDK mapping

| Commerce contract                                      | SDK surface                                                                  |
| ------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `BifyCommercePaymentRouter` and `BifyCommerceCheckout` | `checkout.createOrderSession`, hosted payment confirmation                   |
| `BifyCommercePurchaseRegistry`                         | `checkout.retrieve`, `orders.retrieve`, signed settlement events             |
| `BifyProductCertificateController`                     | `claimHostedCertificate`, `mountBifyCertificate`, `certificates.confirmMint` |
| `BifyProductCertificateNFT`                            | Certificate mint transaction submitted by the customer wallet                |
| `BifyRewardCampaignRegistry`                           | `rewards.create`, `rewards.retrieve`, `rewards.claim`                        |
| `BifyRewardClaimController`                            | `mountBifyRewardClaim`, `rewards.confirmClaim`                               |
| `BifyAccessPassRegistry`                               | `access.create`, `access.grant`, `checkAccess`                               |
| `BifyCommerceVoting`                                   | `voting.createPoll`, `castVote`, `checkVote`, `readVotes`                    |

The SDK abstracts the contract calls used by the standard Commerce flow. A partner should use direct contract calls only when it needs a custom UI or custom transaction orchestration.

## Commerce boundary

The BIFY SDK does not provide product registration, BIFY inventory, BIFY price authority, card or fiat settlement, resale, marketplace trading, yield, managed wallets, or a BIFY token reward vault.


---

# 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://bify.gitbook.io/rwa-docs/bify-sdk/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.