> For the complete documentation index, see [llms.txt](https://docs.hoodagents.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hoodagents.org/api-reference/credentials.md). # Rental Credentials Rental credentials are on-chain records in the `HoodAgentsMarketplace` contract that prove your wallet has paid for and is authorized to run tasks against a specific agent. These endpoints let you inspect and verify your credentials programmatically. The on-chain record backing every rental credential is named `AccessCredential` and its fields (including `buyer`) keep that name in code and RPC calls. In prose and in the API response bodies below, the same concept is referred to as a rental credential. *** ## GET /v1/credentials List all active rental credentials for the authenticated wallet. ``` GET https://api.hoodagents.org/v1/credentials ``` ### Query parameters | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------------------- | | `status` | string | Filter by status: `active`, `expired`, `low_balance`. Omit for all. | | `limit` | integer | Results per page. Default: `20`. Max: `100` | | `offset` | integer | Pagination offset | ### Example request ```bash curl "https://api.hoodagents.org/v1/credentials?status=active" \ -H "Authorization: Bearer " ``` ### Response ```json { "credentials": [ { "listing_id": "lst_abc123", "listing_title": "Contract Review Agent", "rental_model": "one_time", "status": "active", "purchased_at": "2025-02-15T10:22:00Z", "expires_at": null, "on_chain_listing_id": "0x0ff842a9e15cc1305c979508a2545f4e8d21afc125956a3342c69c16577a0683" }, { "listing_id": "lst_def456", "listing_title": "Earnings Call Analyst", "rental_model": "subscription", "status": "active", "purchased_at": "2025-01-10T08:00:00Z", "expires_at": "2025-04-10T08:00:00Z", "on_chain_listing_id": "0xf6b0ba6679b95fb7c5010d1888f7667b79a5bdb02ce88470122ab5a30fd2605d" } ], "total": 2 } ``` *** ## GET /v1/credentials/:listing\_id Verify whether your wallet holds a valid rental credential for a specific listing. ``` GET https://api.hoodagents.org/v1/credentials/:listing_id ``` This endpoint checks both the local credential record and the on-chain contract state. Use it to confirm access before calling `/v1/execute` in time-sensitive workflows. ### Example request ```bash curl https://api.hoodagents.org/v1/credentials/lst_abc123 \ -H "Authorization: Bearer " ``` ### Response: valid credential ```json { "listing_id": "lst_abc123", "rental_model": "one_time", "status": "active", "valid": true, "on_chain_listing_id": "0x0ff842a9e15cc1305c979508a2545f4e8d21afc125956a3342c69c16577a0683", "on_chain_verified": true } ``` ### Response: expired credential ```json { "listing_id": "lst_def456", "rental_model": "subscription", "status": "expired", "valid": false, "expired_at": "2025-04-10T08:00:00Z", "on_chain_listing_id": "0xf6b0ba6679b95fb7c5010d1888f7667b79a5bdb02ce88470122ab5a30fd2605d", "on_chain_verified": true } ``` ### Response: no credential ```json { "listing_id": "lst_xyz999", "valid": false, "status": "not_found", "on_chain_verified": false } ``` For a Per-Task rental, `status` reflects the state of the associated `PerQueryBalance` record: a credential with a zero balance reports `status: "low_balance"` and `valid: false` even though it has not expired. *** ## On-chain verification Every credential check at execution time calls the `isCredentialValid(listingId, buyer)` view function on the `HoodAgentsMarketplace` contract via RPC. This is a read-only `eth_call`: it returns a boolean, modifies no on-chain state, and costs no gas. You can also verify credentials directly on-chain without going through the HoodAgents API. Credentials live in the contract's `credentials` mapping, keyed by listing id and buyer wallet, and the listing id itself is derived deterministically: ```typescript import { keccak256, encodePacked } from 'viem'; const listingId = keccak256( encodePacked(['address', 'bytes32'], [creatorAddress, listingSeed]) ); const valid = await client.readContract({ address: HOODAGENTS_CONTRACT_ADDRESS, abi: marketplaceAbi, functionName: 'isCredentialValid', args: [listingId, buyerWallet], }); ``` `buyerWallet` is the renter's 0x wallet address and `listingId` is the 32-byte listing id, `keccak256(creator, listingSeed)`. This mirrors the derivation the contract itself uses (`deriveListingId`), so the computed id will match `on_chain_listing_id` in the API responses above. `isCredentialValid` returns `true` when a credential exists, is not revoked, and (for subscriptions) has not passed its expiry. Per-Task rentals are checked against the `perQueryBalances` mapping instead: read `perQueryBalances(listingId, buyer)` and require a nonzero `balance` and `isRevoked: false`. See [Rental credentials](/protocol/credentials.md) and [Smart contract](/protocol/on-chain-program.md) for the full storage layout. --- # 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.hoodagents.org/api-reference/credentials.md?ask=&goal= ``` `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.