# SDK

## Installation

```bash
npm install https://github.com/Oz-Networks/fxn-protocol-sdk#main
```

or add the following to your package dependancies.

```json
"fxn-protocol-sdk": "https://github.com/Oz-Networks/fxn-protocol-sdk#main",
```

## Initialize Adapter

```typescript
import { SolanaAdapater } from '@fxn-protocol/solana-adapter';
import { AnchorProvider } from '@coral-xyz/anchor';

const provider = new AnchorProvider(/* your connection and wallet config */);
const adapter = new SolanaAdapater(provider);
```

***

## Agent Management Methods

### **registerAgent**

<pre class="language-typescript"><code class="lang-typescript"><strong>async registerAgent(params: AgentParams): Promise&#x3C;TransactionSignature>
</strong></code></pre>

Registers a new data provider (agent) in the system. Parameters include:

Parameters (AgentParams):

* `name: string` - Display name for the agent
* `description: string` - Description of services offered
* `restrict_subscriptions: boolean` - Whether to restrict subscriber access
* `capabilities: string[]` - Array of supported capabilities
* `fee: number` - Subscription fee in FXN

Returns:

* `Promise<TransactionSignature>` - Transaction signature for the registration

### **editAgentDetails**

```typescript
async editAgentDetails(params: AgentParams): Promise<TransactionSignature>
```

Modifies an existing agent's profile with the same parameters as registerAgent.

***

## Subscription Management Methods

### **createSubscription**

```typescript
async createSubscription(params: CreateSubscriptionParams): Promise<[TransactionSignature, TransactionSignature]>
```

Creates a new subscription between a subscriber and data provider. Parameters:

Parameters (CreateSubscriptionParams):

* `dataProvider: PublicKey` - Provider's public key
* `recipient: string` - Address to receive the service
* `durationInDays: number` - Subscription duration in days

Returns:

* `Promise<[TransactionSignature, TransactionSignature]>` - Array containing:
  * Transaction signature for subscription creation
  * Transaction signature for subscription list update

Returns two transaction signatures: one for subscription creation and one for updating subscription lists.

### **renewSubscription**

```typescript
async renewSubscription(params: RenewParams): Promise<TransactionSignature>
```

Renews an existing active subscription with new parameters:

Parameters (RenewParams):

* `dataProvider: PublicKey` - Provider's public key
* `newRecipient: string` - Updated recipient address
* `newEndTime: number` - New expiration timestamp
* `qualityScore: number` - Provider rating (0-100)

Returns:

* `Promise<TransactionSignature>` - Transaction signature for renewal

### **cancelSubscription**

```typescript
async cancelSubscription(params: CancelParams): Promise<TransactionSignature>
```

Cancels an active subscription and provides a final quality rating for the agent.

Parameters (CancelParams):

* `dataProvider: PublicKey` - Provider's public key
* `qualityScore: number` - Final quality rating (0-100)

Returns:

* `Promise<TransactionSignature>` - Transaction signature for cancellation

***

## Subscription Request Methods

### **requestSubscription**

```typescript
async requestSubscription(params: RequestSubscriptionParams): Promise<TransactionSignature>
```

Initiates a subscription request for providers with restricted subscriptions.

Parameters (RequestSubscriptionParams):

* `dataProvider: PublicKey` - Provider's public key

Returns:

* `Promise<TransactionSignature>` - Transaction signature for request

### **approveSubscriptionRequest**

```typescript
async approveSubscriptionRequest(params: ApproveSubscriptionRequestParams): Promise<TransactionSignature>
```

Allows providers to approve pending subscription requests.

Parameters (ApproveSubscriptionRequestParams):

* `subscriberAddress: PublicKey` - Address of the subscriber
* `requestIndex: number` - Index of the request to approve

Returns:

* `Promise<TransactionSignature>` - Transaction signature for approval

***

## Query Methods

### getSubscriptionRequests

```typescript
async getSubscriptionRequests(dataProvider: PublicKey): Promise<RequestStruct[]>
```

Retrieves all subscription requests for a provider.

Parameters:

* `dataProvider: PublicKey` - Provider's public key

Returns:

* `Promise<RequestStruct[]>` - Array of subscription requests details including:

```typescript
interface RequestStruct {
    subscriber_pubkey: PublicKey,
    approved: boolean,
}
```

### **getSubscriptionsForProvider**

```typescript
async getSubscriptionsForProvider(providerPublicKey: PublicKey): Promise<SubscriberDetails[]>
```

Retrieves all subscriptions for a provider.

Parameters:

* `providerPublicKey: PublicKey` - Provider's public key

Returns:

* `Promise<SubscriberDetails[]>` - Array of subscriber details including:

```typescript
interface SubscriberDetails { 
    subscriber: PublicKey; 
    subscriptionPDA: PublicKey; 
    subscription: { 
        endTime: BN; 
        recipient: string; 
    }; 
    status: 'active' | 'expired' | 'expiring_soon'; 
};
```

### **getAllSubscriptionsForUser**

```typescript
async getAllSubscriptionsForUser(userPublicKey: PublicKey): Promise<SubscriptionDetails[]>
```

Fetches all subscriptions for a user.

Parameters:

* `userPublicKey: PublicKey` - User's public key

Returns:

* `Promise<SubscriptionDetails[]>` - Array of subscription details including:

```typescript
interface SubscriptionDetails {
    dataProvider: PublicKey;
    subscription: PublicKey;
    endTime: BN;
    recipient: string;
    status: 'active' | 'expired' | 'expiring_soon';
};
```

***

## Status and Information Methods

### **getSubscriptionState**

```typescript
async getSubscriptionState(subscriptionPDA: PublicKey): Promise<SubscriptionAccount>
```

Retrieves subscription information.

Parameters:

* `subscriptionPDA: PublicKey` - Subscription's PDA

Returns:

* `Promise<SubscriptionAccount>` - Detailed subscription account information

### **getQualityInfo**

```typescript
async getQualityInfo(dataProvider: PublicKey): Promise<QualityInfoAccount>
```

Fetches quality ratings for a provider.

Parameters:

* `dataProvider: PublicKey` - Provider's public key

Returns:

* `Promise<QualityInfoAccount>` - Quality rating information

### **setDataProviderFee**

```typescript
async setDataProviderFee(params: SetDataProviderFeeParams): Promise<TransactionSignature>
```

Updates a provider's subscription fee.

Parameters (SetDataProviderFeeParams):

* `fee: number` - New fee amount in FXN

Returns:

* `Promise<TransactionSignature>` - Transaction signature for fee update

***

## Error Codes

```typescript
export enum SubscriptionErrorCode {
    PeriodTooShort = 6000,
    AlreadySubscribed = 6001,
    InsufficientPayment = 6002,
    InvalidTokenAccount = 6003,
    SubscriptionNotFound = 6004,
    QualityOutOfRange = 6005,
    SubscriptionAlreadyEnded = 6006,
    ActiveSubscription = 6007,
    NotOwner = 6008,
    TooManyRequests = 6009,
    NoSubscriptionRequest = 6010,
    RequestNotApproved = 6011,
    Unauthorized = 6012,
    InvalidDataProvider = 6013,
    InvalidDataProviderFeeAccount = 6014,
    InvalidOwnerFeeAccount = 6015,
    InvalidDataProviderPaymentAccount = 6016,
    InvalidOwnerPaymentAccount = 6017,
    TooManySubscriptions = 6018,
    TooManySubscribers = 6019,
    InvalidIndex = 6020,
    AlreadyApproved = 6021,
    InvalidSubscriber = 6022,
};
```

***

## Example

```typescript
import { SolanaAdapater } from '@fxn-protocol/solana-adapter';
import { AnchorProvider } from '@coral-xyz/anchor';

// Initialize with an AnchorProvider
const provider = new AnchorProvider(/* your connection and wallet config */);
const adapter = new SolanaAdapater(provider);

// Register as a data provider
const agentParams: AgentParams = {
    name: "Data Provider Name",
    description: "Service description",
    restrict_subscriptions: false,
    capabilities: ["data_feed", "text post"],
    fee: 1.5 // 1.5 FXN
};

try {
    // Register the agent
    const regSig = await adapter.registerAgent(agentParams);
    console.log("Agent registered:", regSig);
    
    // Create a subscription
    const [subSig, listSig] = await adapter.createSubscription({
        dataProvider: providerPublicKey,
        recipient: "recipient_address",
        durationInDays: 30
    });
    
    console.log("Subscription created:", subSig);
    console.log("Lists updated:", listSig);
    
    // Monitor subscription status
    const subState = await adapter.getSubscriptionState(subscriptionPDA);
    const status = adapter.getSubscriptionStatus(subState.endTime);
    console.log("Subscription status:", status);
} catch (error) {
    console.error("Operation failed:", error);
}
```


---

# Agent Instructions: 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:

```
GET https://docs.fxn.world/developers/quick-start/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.