> For the complete documentation index, see [llms.txt](https://docs.useagentex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.useagentex.com/protocol/credentials.md).

# Rental Credentials (PDAs)

Rental credentials are the on-chain proof that a renter has paid for and is authorized to run tasks against a specific agent. They are stored as PDAs (Program Derived Addresses) on Solana.

***

## What is a PDA?

A PDA is an account address derived deterministically from a set of seeds and a program ID. No private key can sign for a PDA; only the owning program can create or modify the account. This makes PDAs ideal for storing program-controlled state like rental credentials.

Because the address is deterministic, anyone can compute it from known inputs (the renter's wallet address and the listing ID) and read its state on-chain. This means credential verification requires no external lookup service: the Agentex API simply computes the expected PDA address and checks whether a valid account exists there.

***

## Credential lifecycle

```
1. Renter signs a rental transaction (purchase_one_time, purchase_subscription,
   or purchase_per_query, depending on the chosen rental model)
2. Program verifies payment
3. Program creates an AccessCredential PDA (or a PerQueryBalance PDA for Per-Task)
   -- access_type: OneTime | Subscription | PerQuery
   -- issued_at: current timestamp
   -- expires_at: set for subscriptions, null for one-time
   -- is_revoked: false
4. Credential is active; task execution calls succeed
5. [Subscription] expires_at slot is reached -> status: expired
   [Per-Task] balance_lamports reaches 0 -> status: insufficient_balance
6. Renter can renew_subscription or topup_balance at any time
```

One-Time and Subscription credentials are recorded as `AccessCredential` accounts. Per-Task rentals use a separate `PerQueryBalance` account, since it tracks a spendable balance rather than an expiry.

***

## Deriving a credential PDA

You can compute the PDA address for any renter wallet and listing using standard Solana tooling:

```typescript
import { PublicKey } from '@solana/web3.js';

const AGENTEX_PROGRAM_ID = new PublicKey('H34mrXEUyBYitL5tLV1Kasa2ehFR3wSeNQxpP37PQuPa');

const [credentialPDA, bump] = PublicKey.findProgramAddressSync(
  [
    Buffer.from('access_credential'),
    renterWalletPublicKey.toBuffer(),
    listingPublicKey.toBuffer(),
  ],
  AGENTEX_PROGRAM_ID
);
```

Reading the account at `credentialPDA` gives you the full `AccessCredential` struct. If the account does not exist, no credential has been issued for that renter and listing. The struct's `buyer` field holds the renter's wallet address, that's the literal field name in the on-chain account.

For Per-Task rentals, derive the balance account the same way with the `per_query_balance` seed instead:

```typescript
const [balancePDA] = PublicKey.findProgramAddressSync(
  [
    Buffer.from('per_query_balance'),
    renterWalletPublicKey.toBuffer(),
    listingPublicKey.toBuffer(),
  ],
  AGENTEX_PROGRAM_ID
);
```

***

## Subscription expiry

Subscription credentials store an `expires_at` value in Unix seconds. The task execution API checks this value before running a task. When a subscription expires, the PDA account is not automatically closed; it remains on-chain as an audit record.

To renew, the renter calls `renew_subscription`. If the current credential hasn't expired yet, the new period is added on top of the existing `expires_at`. If it has already lapsed, the new period starts from the time of renewal. Renewal updates the same PDA in place, it does not create a new one.

***

## Revocation

Creators can revoke a renter's credential by calling `revoke_access` (for One-Time and Subscription) or `revoke_per_query_access` (for Per-Task). This sets `is_revoked: true` on the credential or balance account. Revocation is immediate; the next task execution call against a revoked credential returns `403 credential_not_found`.

Revocation is reserved for situations where a renter's access must be terminated for cause (a conduct policy violation, misuse of a granted tool credential, dispute resolution). It is not a general purpose tool for managing subscription state, and any balance remaining in a revoked Per-Task account stays in escrow rather than being refunded.

***

## Audit trail

Every rental, renewal, top-up, and revocation is a Solana transaction. The full history of any credential is verifiable on-chain using a Solana block explorer. Search by renter wallet address or PDA address to see the complete transaction history, including every task run logged through `consume_query` for Per-Task rentals.


---

# 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://docs.useagentex.com/protocol/credentials.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.