> For the complete documentation index, see [llms.txt](https://docs.yield.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yield.fi/earn-with-yieldfi/integration-sdk/api-reference/glassbook-api.md).

# Glassbook API

The Glassbook API provides endpoints for managing partner transactions (PTX) and referrals. All endpoints require authentication.

### Partner Transactions (PTX)

#### Create Partner Transaction

Create a new partner transaction record.

```typescript
const accessToken = localStorage.getItem("accessToken");

const ptx = await sdk.glassbook.createPartnerTransaction(accessToken, {
  transactionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  chainId: "1", // Ethereum
});

console.log(`PTX created: ${ptx.ptx.id}`);
console.log(`Status: ${ptx.ptx.status}`);
```

#### Get Partner Transactions

Get all partner transactions with pagination and filters.

```typescript
const accessToken = localStorage.getItem("accessToken");

const transactions = await sdk.glassbook.getPartnerTransactions(accessToken, {
  page: 1,
  pageSize: 10,
  chainId: "1", // Optional filter
});

console.log(`Found ${transactions.pagination.total} transactions`);
transactions.data.forEach((tx) => {
  console.log(`PTX ${tx.id}: ${tx.transactionHash} - ${tx.status}`);
});
```

#### Get My Partner Transactions

Get the authenticated user's partner transactions.

```typescript
const accessToken = localStorage.getItem("accessToken");

const myTransactions = await sdk.glassbook.getMyPartnerTransactions(accessToken);

console.log(`You have ${myTransactions.pagination.total} partner transactions`);
```

#### Get Partner Transaction by ID

Get a specific partner transaction by its ID.

```typescript
const accessToken = localStorage.getItem("accessToken");

const transaction = await sdk.glassbook.getPartnerTransactionById(accessToken, 123);

console.log(`Transaction: ${transaction.ptx.transactionHash}`);
console.log(`Status: ${transaction.ptx.status}`);
```

### Referrals

#### Get My Referral

Get the authenticated user's referral information.

```typescript
const accessToken = localStorage.getItem("accessToken");

const myReferral = await sdk.glassbook.getMyReferral(accessToken);

console.log(`Your referral code: ${myReferral.referral.code}`);
console.log(`Referred by: ${myReferral.referral.referredBy || "None"}`);
```

#### Get My Referral Stats

Get referral statistics for the authenticated user.

```typescript
const accessToken = localStorage.getItem("accessToken");

const stats = await sdk.glassbook.getMyReferralStats(accessToken);

console.log(`Total referred: ${stats.stats.totalReferred}`);
console.log(`Active referrals: ${stats.stats.activeReferred}`);
```

#### Get My Referred Addresses

Get addresses that were referred by the authenticated user.

```typescript
const accessToken = localStorage.getItem("accessToken");

const referred = await sdk.glassbook.getMyReferredAddresses(accessToken, 1, 10);

console.log(`You referred ${referred.pagination.total} addresses`);
referred.data.forEach((address) => {
  console.log(`  ${address.address} - Joined: ${address.joinedAt}`);
});
```

#### Create Referral

Create a new referral with a custom code.

```typescript
const accessToken = localStorage.getItem("accessToken");

const referral = await sdk.glassbook.createReferral(accessToken, {
  code: "MYCODE123",
  referredBy: "REFERRER_CODE", // Optional: if user was referred
});

console.log(`Referral created: ${referral.referral.code}`);
```

#### Check Referral Code Availability

Check if a referral code is available.

```typescript
const accessToken = localStorage.getItem("accessToken");

const availability = await sdk.glassbook.checkReferralCodeAvailability(
  accessToken,
  "MYCODE123"
);

if (availability.available) {
  console.log("Code is available!");
} else {
  console.log("Code is already taken");
}
```

#### Get Referral by Code

Get referral information by code.

```typescript
const accessToken = localStorage.getItem("accessToken");

const referral = await sdk.glassbook.getReferralByCode(accessToken, "MYCODE123");

console.log(`Referral code: ${referral.referral.code}`);
console.log(`Owner: ${referral.referral.address}`);
```

#### Get Referral by Address

Get referral information by address.

```typescript
const accessToken = localStorage.getItem("accessToken");

const referral = await sdk.glassbook.getReferralByAddress(
  accessToken,
  "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
);

console.log(`Referral code: ${referral.referral.code}`);
```

### Complete Example

```typescript
import { YieldFiSDK } from "yieldfi-sdk";

async function referralFlow() {
  const sdk = await YieldFiSDK.create({
    gatewayUrl: "https://gw.yield.fi",
  });

  const accessToken = localStorage.getItem("accessToken");

  // 1. Get or create referral code
  let myReferral;
  try {
    myReferral = await sdk.glassbook.getMyReferral(accessToken);
    console.log(`Your existing code: ${myReferral.referral.code}`);
  } catch (error) {
    // No referral exists, create one
    const code = `USER${Date.now()}`;
    const available = await sdk.glassbook.checkReferralCodeAvailability(
      accessToken,
      code
    );

    if (available.available) {
      myReferral = await sdk.glassbook.createReferral(accessToken, {
        code,
      });
      console.log(`Created new code: ${myReferral.referral.code}`);
    }
  }

  // 2. Get referral stats
  const stats = await sdk.glassbook.getMyReferralStats(accessToken);
  console.log(`Total referred: ${stats.stats.totalReferred}`);

  // 3. Get referred addresses
  const referred = await sdk.glassbook.getMyReferredAddresses(accessToken, 1, 10);
  console.log(`Referred addresses: ${referred.data.length}`);

  // 4. Create partner transaction
  const ptx = await sdk.glassbook.createPartnerTransaction(accessToken, {
    transactionHash: "0x...",
    chainId: "1",
  });
  console.log(`PTX created: ${ptx.ptx.id}`);
}

referralFlow();
```

### Next Steps

* Forms API - Dynamic form handling
* Examples - More examples