# API

***

## Trending Arts

Fetches a list of currently trending artworks on the Phi.Box platform, including metadata like title, image, artist info, and minting URL.

#### Endpoint

```
GET https://phi.box/api/trending-arts
```

#### Response Format

Returns a JSON array of trending artworks with the following fields:

```
[
  {
    "key": "8453-1",
    "url": "https://phi.box/mint/8453-1/8453-1",
    "credChainId": "8453",
    "credId": "1",
    "artChainId": "8453",
    "artId": "1",
    "name": "Base Cosmic Maker",
    "image": "https://arweave.net/HKjoGyUJIz9e-WHPuIs2A94awBFDvXSS3mezJx6FQDQ",
    "artist": "0xe55036b78702961e72a27d21c3eb78c71bb6a645",
    "artistENSName": "edurubio.eth",
    "project": "Base"
  }
]

```

#### Field Descriptions

| Field         | Type        | Descript                                             |
| ------------- | ----------- | ---------------------------------------------------- |
| key           | string      | Unique identifier composed of credChainId and artId. |
| url           | string      | Direct URL to mint or view the artwork.              |
| credChainId   | string      | Chain ID associated with the credential.             |
| credId        | string      | Credential ID indicating the collection or origin.   |
| artChainId    | string      | Chain ID of the artwork.                             |
| artId         | string      | Unique identifier of the artwork.                    |
| name          | string      | Title of the artwork.                                |
| image         | string      | Arweave-hosted image URL for the artwork.            |
| artist        | string      | Ethereum address of the artist.                      |
| artistENSName | string/null | ENS name of the artist if available.                 |
| project       | string      | Project or collection name. Usually "Base".          |

#### Example Request

```
GET https://phi.box/api/trending-arts
```

#### Example Response

```
[
  {
    "key": "8453-1",
    "url": "https://phi.box/mint/8453-1/8453-1",
    "credChainId": "8453",
    "credId": "1",
    "artChainId": "8453",
    "artId": "1",
    "name": "Base Cosmic Maker",
    "image": "https://arweave.net/HKjoGyUJIz9e-WHPuIs2A94awBFDvXSS3mezJx6FQDQ",
    "artist": "0xe55036b78702961e72a27d21c3eb78c71bb6a645",
    "artistENSName": "edurubio.eth",
    "project": "Base"
  },
  ...
]

```

#### Notes

* ENS names may be null if not set by the artist.
* All images are hosted on Arweave, ensuring permanence.
* The key can be used as a unique identifier in frontend components or UI render loops.

***

## PHI Trusted Artists

Returns a list of Ethereum addresses of artists who are trusted by the PHI community. These addresses represent verified or curated creators whose artworks are eligible for specific features or recognition within the platform.

#### Endpoint

```
https://base.terminal.phi.box/api/phi-trusted-artists
```

#### Response Format

```
[
  "0xdc37e6f67bfb7361e25731fc477903e172d211f1",
  "0x0b81bffce9970aca9868120eee1bcc8de19119f7",
  "0x2d0557f9e557052924b15abb3d0153769504b8de"
]
```

#### Example Request

```
GET https://base.terminal.phi.box/api/phi-trusted-artist
```

#### Example Response

```
[
  "0xdc37e6f67bfb7361e25731fc477903e172d211f1",
  "0x0b81bffce9970aca9868120eee1bcc8de19119f7",
  "0x2d0557f9e557052924b15abb3d0153769504b8de"
]
```

#### Notes

* This list can be used for filtering, verification, or giving special status to artworks from verified creators.
* The order of addresses is not guaranteed to be meaningful (i.e., not sorted by activity or reputation).
* You can cross-reference these addresses with artwork metadata to verify the artist’s PHI-trusted status.

***

## Pin Image

Fetches the currently pinned artwork(s) for a given wallet address on the PHI platform.

#### Endpoint

```
GET https://phi.box/profile/{wallet_address}/pin
```

#### Example Request

```
https://phi.box/profile/0x5cD18dA4C84758319C8E1c228b48725f5e4a3506/pin
```

#### Example Response

```
{
  "artChainIds": ["8453"],
  "artIds": ["1379"],
  "url": "https://phi.box/mint/8453-1/8453-1379"
}
```

***

## Minter List (Art)

Fetches the list of wallet addresses that minted a specific artwork (token) from a given contract on the PHI platform.

#### Endpoint

```
GET https://base.terminal.phi.box/art/{contract_address}/{token_id}/mint-activity
```

#### Query Parameters

| Key   | Type   | Required | Description                                                        |
| ----- | ------ | -------- | ------------------------------------------------------------------ |
| limit | number | Optional | Number of entries to return (default varies, max recommended 100). |

#### Example Request:

```
GET https://base.terminal.phi.box/art/base:0x6a752405Abd3F7Ec88001F141E0A0FcFbb068502/1/mint-activity?limit=100
```

#### Response Format

Returns a JSON array of wallet addresses that minted the specified token:

```
[
  "0xadfbc608bbae9ccbfaff88b2f12de0b2b2bb50d8",
  "0xb52e85d8962b874088e4ff146b1e8e46d7422a35",
  "0x7b8f0b8e09ca522ad3418fb89b9176f1bc74644c",
  ...
]
```

#### Notes

* contract\_address must be in the format: base:0x... (including the prefix for L2 chains like Base).
* Commonly used in analytics, community insights, or airdrop planning.
* No pagination yet, but use limit to restrict data size for performance.

***

## Credentials List

Returns a list of all available creds. Each cred includes its title, eligibility requirement, type, verification method, creator address, and other associated metadata.

#### Example Request

```
GET https://base.terminal.phi.box/api/cred
```

#### Example Response

```
{
  "total": 286,
  "records": [
    {
      "chain_id": "8453",
      "id": "132",
      "cred_type": "BASIC",
      "verification_type": "SIGNATURE",
      "creator": "0xafa6a55f941aae3c6432901236291f4347a19715",
      "metadata_version": "1.0",
      "uuid": "7347866e-4ae7-423c-a56a-1dd5b1e6ff99",
      "title": "Base Early Adopter",
      "requirement": "Transacted on Base at launch month.",
      "image": "https://arweave.net/sGX5udKOViLkudYH9ZOpc92gTdTTs_PS67mFKiED8oM",
      "networks": ["8453"],
      "tags": [],
      "related_links": ["https://www.base.org/"],
      "project": "",
      "created_at": "2025-02-25T03:52:16.417Z",
      "updated_at": "2025-02-25T03:52:16.417Z",
      "total_buy": "1",
      "total_sell": "0",
      "total_traded": "1",
      "latest_supply": "1"
    },
    {
      "chain_id": "8453",
      "id": "131",
      "cred_type": "BASIC",
      "verification_type": "SIGNATURE",
      "creator": "0xafa6a55f941aae3c6432901236291f4347a19715",
      "metadata_version": "1.0",
      "uuid": "587b360a-a7dd-43d4-9850-1d8c7a37195b",
      "title": "$KAITO Holder",
      "requirement": "Hold $KAITO Tokens",
      "image": "https://arweave.net/Vr4fePnmDx1pken-90KHhLzK8gSnzhejXf1eD2x2gog",
      "networks": ["8453"],
      "tags": [],
      "related_links": ["https://www.kaito.ai/"],
      "project": "",
      "created_at": "2025-02-21T12:03:30.752Z",
      "updated_at": "2025-02-21T12:03:30.752Z",
      "total_buy": "4",
      "total_sell": "0",
      "total_traded": "4",
      "latest_supply": "4"
    },
    ...
  ]
}

```

#### Use Case

* Display available creds
* Allow users to browse drops they may be eligible for
* Enable developers to query and filter based on cred\_type, tags, or related projects

***

## Art List

This endpoint retrieves a list of art records related to a specified chain. Each art record contains various metadata, such as details about the artist, the associated credential, and the associated images. This endpoint is primarily used to fetch art data stored on the system.

#### End Point

```
https://base.terminal.phi.box/api/art
```

#### Query Parameters

* limit (optional): Specifies the maximum number of art records to return in the response. Default is typically 100 if not specified.
  * Example: limit=2 will return only 2 records.

#### Response Structure

The response will be a JSON object containing the following properties:

* total: The total number of art records available.
* records: An array of art records, where each record contains the metadata for an individual art piece.

#### Example Response

```
{
  "total": 1703,
  "records": [
    {
      "cred_chain_id": "8453",
      "cred_id": "1",
      "art_chain_id": "8453",
      "art_id": "1472",
      "token_id": "331",
      "art_address": "0x26d858a412f010ea89aad08d4759a757f52c172d",
      "artist": "0x4e0658e1e379faf0b96b78cfe7051f87c07900e2",
      "receiver": "0x4e0658e1e379faf0b96b78cfe7051f87c07900e2",
      "start_time": "2025-04-14T14:00:00.000Z",
      "end_time": "2125-04-14T14:00:00.000Z",
      "mint_fee": "400000000000000",
      "max_supply": "6900",
      "soulbounded": false,
      "cred_type": "ADVANCED",
      "verification_type": "SIGNATURE",
      "name": "BARIZARD",
      "description": "",
      "image": "https://arweave.net/9-SmQ-WOyp-YwJ81jKZ2RxJkdIbWnZ23IHThRjwuoeo",
      "art_type": "IMAGE",
      "endpoint": "",
      "external_url": "https://base.terminal.phi.box/cred/1",
      "created_at": "2025-04-14T14:00:38.324Z",
      "updated_at": "2025-04-14T16:58:51.311Z",
      "attributes": [
        {
          "value": "Base",
          "trait_type": "cred_project"
        },
        {
          "value": "Transaction",
          "trait_type": "cred_tag"
        },
        {
          "value": "backdrop",
          "trait_type": "art_tag"
        }
      ],
      "total_mint": "1",
      "cred": {
        "chain_id": 8453,
        "id": 1,
        "cred_type": "ADVANCED",
        "verification_type": "SIGNATURE",
        "creator": "0x6e4a4525c1b0f9237acc0ab8da9a1934ef75ba94",
        "metadata_version": "1.0",
        "uuid": "f31701a5-c8d3-48aa-9668-4e543f6c3d8d",
        "title": "Transact on Base",
        "requirement": "Execute any transaction on Base chain",
        "image": "https://arweave.net/xOPkyqPaX9jyYDN1a9ACVg89qg9MZGmwp7NG_Oomd2E",
        "networks": [
          "8453"
        ],
        "tags": [
          "Transaction"
        ],
        "related_links": [
          "https://base.org/"
        ],
        "project": "Base",
        "created_at": "2024-10-13T07:54:54.591",
        "updated_at": "2024-10-13T07:54:54.591"
      }
    }
  ]
}
```

***

## Eligibility Check

This API checks the eligibility of a given wallet address for minting specific creds or participating in trending art campaigns. The request can be made to check either "trending" art or specific creds based on the provided parameters. The system supports rate limiting, authentication via API key, and error handling for both invalid requests and service disruptions.

```
GET https://prod.phi-api.xyz/eligible-check
```

#### Query Parameter

> **type:** (Required) The type of eligibility check. Options:\
> \
> \&#xNAN;**"trending":** Check eligibility for trending art.\
> \
> "**specific":** Check eligibility for specific creds.\
> \
> **address:** (Required) The wallet address to check eligibility for (in hex format).\
> \
> **referrer:** (Optional) The referrer’s wallet address (in hex format). If provided, referrers earn 0.00005 ETH per mint.\
> \
> **specificCreds:** (Optional) Only required if type is "specific". This is an array of specific creds to check. Each item should have the following format:\
> \
> **credChainId:** The chain ID where the cred exists.\
> \
> **credId:** The ID of the specific cred.

#### Response Structure

The response will include eligibility results based on the provided type. It will return a JSON object with keys for each item being checked, indicating whether the address is eligible and providing additional details like a URL for minting (if applicable).

#### Response for Trending Art:

```
{
  "trending_art_key": {
    "eligible": true,
    "url": "https://phi.box/mint/8453-1/8453-1472?referrer=0x4e0658e1e379faf0b96b78cfe7051f87c07900e2"
  }
}
```

#### Response for Specific Cred:

```
{
  "8453-1": {
    "eligible": true
  }
}
```

* eligible: Boolean value indicating whether the address is eligible to mint.
* url (optional): If the check type is "trending", the URL for minting will be included. If the referrer is provided, it will be appended to the URL.

#### Rate Limiting

The API enforces rate limiting to ensure fair usage. You can make up to 5 requests per second. If this limit is exceeded, the system will respond with a 429 status and suggest trying again after a short delay.<br>

***

#### Eligible List&#x20;

Returns a list of all currently eligible trending artworks for a given wallet acting as a referrer. This API helps track which trending art pieces can be minted using a particular referrer link (i.e., those the wallet is eligible for).

#### Endpoint

```
GET https://prod.phi-api.xyz/eligible-list?referrer={wallet_address}
```

#### Query Parameters

| Parameter | Type                 | Required | Description                                                         |
| --------- | -------------------- | -------- | ------------------------------------------------------------------- |
| referrer  | string (hex address) | Yes      | Wallet address (in hex format) for which to fetch eligible artworks |

#### Example Request

```
curl -X GET "https://prod.phi-api.xyz/eligible-list?referrer=0x5037e7747fAa78fc0ECF8DFC526DcD19f73076ce"
```

#### Response Format

```
[
  {
    "key": "bengal-backdrop-transaction",
    "credChainId": 8453,
    "credId": "1",
    "artChainId": "8453",
    "artId": "1471",
    "name": "BENGAR",
    "image": "https://arweave.net/Q0tPxy-8P7GH_g5TDVWeLb4ZYuvxmQbTP3udiL-Pxbw",
    "artist": "0x4e0658e1e379faf0b96b78cfe7051f87c07900e2",
    "artistENSName": null,
    "project": "Base",
    "url": "https://phi.box/mint/8453-1/8453-1471?referrer=0x5037e7747fAa78fc0ECF8DFC526DcD19f73076ce"
  },
  {
    "key": "barizard-backdrop-transaction",
    "credChainId": 8453,
    "credId": "1",
    "artChainId": "8453",
    "artId": "1472",
    "name": "BARIZARD",
    "image": "https://arweave.net/9-SmQ-WOyp-YwJ81jKZ2RxJkdIbWnZ23IHThRjwuoeo",
    "artist": "0x4e0658e1e379faf0b96b78cfe7051f87c07900e2",
    "artistENSName": null,
    "project": "Base",
    "url": "https://phi.box/mint/8453-1/8453-1472?referrer=0x5037e7747fAa78fc0ECF8DFC526DcD19f73076ce"
  }
]

```

#### Use Case

* Tracking Referrer Mints: Helps referrers know which artworks they are eligible to promote and earn referral rewards for.
* Eligibility-based UI: Enables wallets to show users personalized mintable content based on referrer eligibility.