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

# Builder Program

> Learn how to get a Renaiss builder API key and integrate it with the TypeScript SDK.

The Renaiss Builder Program is for apps and teams that build gacha, wallet, and buyback experiences on top of Renaiss.

A builder gets an approved `builderApiKey`. Your integration passes that key with a user's Renaiss API key when it calls builder-authorized write workflows through the TypeScript SDK.

## What it enables

Use a builder API key when your integration needs Renaiss to authorize write workflows for a user.

<Columns cols={2}>
  <Card title="Builder-authorized writes" icon="key-round">
    Pair the user's `apiKey` with your approved `builderApiKey` for wallet preparation, gacha pulls, and buybacks.
  </Card>

  <Card title="Gasless transactions" icon="fuel">
    Use sponsored wallet and gacha workflows where Renaiss supports gasless execution.
  </Card>

  <Card title="SDK integration" icon="code">
    Use `createSecureClient({ apiKey, builderApiKey, signer })` in the TypeScript SDK.
  </Card>
</Columns>

You do not need a builder API key for public discovery. Authenticated reads such as `fetchAuthenticatedUser`, `listUserActivities`, and `listGachaBuybackOffers` use the user's API key only.

## Builder API key

A builder API key is an app-level credential issued by Renaiss. It identifies your builder tier and authorizes write workflows from your integration.

The builder API key does not replace the user's API key. Write workflows need both credentials:

* The user's `apiKey`, created with Sign in with Ethereum through `createApiKeyWithSiwe` or issued by the Renaiss API.
* Your `builderApiKey`, provisioned by Renaiss for your app or team.

If a write workflow is missing `builderApiKey`, the SDK returns a `WRONG_REQUEST_PARAMS` result before signing or sending the write request.

### How to get a builder API key

Builder API keys are provisioned manually for now.

<Steps>
  <Step title="Contact Renaiss">
    Email us at [info@renaiss.xyz](mailto:info@renaiss.xyz) or reach out to your Renaiss contact.
  </Step>

  <Step title="Share your integration details">
    Include your app name, use case, expected volume, environments, and the wallet or gacha flows you plan to support.
  </Step>

  <Step title="Receive your key and tier">
    Renaiss reviews the request, assigns a builder tier, and provisions the builder API key for your integration.
  </Step>
</Steps>

## Builder code

A builder code is an optional bytes32 value (`0x` plus 64 hex characters) that attributes a gacha pull to your integration on-chain.

It is a separate concept from the builder API key:

|                   | Builder API key                         | Builder code                           |
| ----------------- | --------------------------------------- | -------------------------------------- |
| Purpose           | Authorizes write workflows              | Attributes a pull on-chain             |
| Required          | Yes, for write workflows                | No                                     |
| Where you pass it | `createSecureClient({ builderApiKey })` | Per call: `pullGacha({ builderCode })` |
| Sensitivity       | Secret, keep it server-side             | Public on-chain data                   |

Pass the code per pull rather than on the client, so you can attribute pulls to different surfaces or campaigns from one integration. When you omit it, the API falls back to the zero bytes32 value.

## Example

Store the builder API key in your app configuration, then pass it to the secure client that performs write workflows. Pass the builder code to each pull you want to attribute.

<CodeGroup>
  ```bash .env theme={null}
  RENAISS_BUILDER_API_KEY=<approved-builder-api-key>
  RENAISS_BUILDER_CODE=0x0000000000000000000000000000000000000000000000000000000000000000
  ```

  ```ts TypeScript theme={null}
  import {
    GachaQuantity,
    createSecureClient,
    getError,
    getValue,
    isFailed,
  } from "@renaiss-protocol/client";
  import { privateKey } from "@renaiss-protocol/client/viem";

  const signer = privateKey(process.env.PRIVATE_KEY);
  const builderApiKey = process.env.RENAISS_BUILDER_API_KEY;

  if (builderApiKey === undefined) {
    throw new Error("Missing RENAISS_BUILDER_API_KEY.");
  }

  const secureClient = createSecureClient({
    apiKey: userApiKey,
    builderApiKey,
    signer,
  });

  const readinessResult = await secureClient.ensureSafeWalletReady();

  if (isFailed(readinessResult)) {
    throw new Error(getError(readinessResult).detail);
  }

  const pullResult = await secureClient.pullGacha({
    builderCode: process.env.RENAISS_BUILDER_CODE,
    machineSlug: "example-machine",
    quantity: GachaQuantity.Single,
  });

  if (isFailed(pullResult)) {
    throw new Error(getError(pullResult).detail);
  }

  console.log(getValue(pullResult).draws);
  ```
</CodeGroup>

<Info>
  `userApiKey` in the example is the user's Renaiss API key. Create it with `createApiKeyWithSiwe` before constructing the secure client.
</Info>

## Next steps

<Columns cols={2}>
  <Card title="TypeScript SDK" icon="code" href="/typescript-sdk">
    Use the builder API key with wallet, pull, and buyback write workflows.
  </Card>

  <Card title="Builder Tiers" icon="layers" href="/builder-tiers">
    Compare builder tiers for limits, gasless transactions, support, and priority access.
  </Card>
</Columns>