> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1tx.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocols API

> Query supported DeFi protocols

## List All Protocols

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/protocols`

Retrieve a list of all supported DeFi protocols.

### Request

```bash theme={null}
curl "https://api.1tx.fi/api/v1/protocols"
```

### Query Parameters

| Parameter | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| `chainId` | number | No       | Filter by chain ID |

### Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Aave",
    "version": 3,
    "displayName": "Aave V3",
    "chainId": 8453,
    "protocolAddress": "0x...",
    "icon": "aave",
    "docsUrl": "https://docs.aave.com",
    "deprecated": false,
    "deprecationReason": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Compound",
    "version": 3,
    "displayName": "Compound V3",
    "chainId": 8453,
    "protocolAddress": "0x...",
    "icon": "compound",
    "docsUrl": "https://docs.compound.finance",
    "deprecated": false,
    "deprecationReason": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Morpho",
    "version": 1,
    "displayName": "Morpho Blue",
    "chainId": 8453,
    "protocolAddress": "0x...",
    "icon": "morpho",
    "docsUrl": "https://docs.morpho.org",
    "deprecated": false,
    "deprecationReason": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  }
]
```

### Response Fields

| Field               | Type    | Description                                          |
| ------------------- | ------- | ---------------------------------------------------- |
| `id`                | string  | Unique protocol identifier (UUID)                    |
| `name`              | string  | Protocol name (Aave, Compound, Morpho, Euler, Fluid) |
| `version`           | number  | Protocol version number                              |
| `displayName`       | string  | Human-readable protocol name with version            |
| `chainId`           | number  | Chain ID where this protocol is deployed             |
| `protocolAddress`   | string  | Main protocol contract address                       |
| `icon`              | string  | Icon identifier for UI display                       |
| `docsUrl`           | string  | Link to protocol documentation                       |
| `deprecated`        | boolean | Whether this protocol version is deprecated          |
| `deprecationReason` | string  | Reason for deprecation (if applicable)               |
| `createdAt`         | string  | ISO 8601 creation timestamp                          |
| `updatedAt`         | string  | ISO 8601 last update timestamp                       |

***

## Get Single Protocol

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/protocols/:id`

Retrieve details for a specific protocol.

### Request

```bash theme={null}
curl "https://api.1tx.fi/api/v1/protocols/550e8400-e29b-41d4-a716-446655440000"
```

### Path Parameters

| Parameter | Type   | Required | Description       |
| --------- | ------ | -------- | ----------------- |
| `id`      | string | Yes      | The protocol UUID |

### Response

The single protocol endpoint returns the protocol object plus its related `instruments` array.

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Aave",
  "version": 3,
  "displayName": "Aave V3",
  "chainId": 8453,
  "protocolAddress": "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",
  "icon": "aave",
  "docsUrl": "https://docs.aave.com",
  "deprecated": false,
  "deprecationReason": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-15T14:30:00.000Z",
  "instruments": [
    {
      "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
      "chainId": 8453,
      "tokenSymbol": "USDC"
    }
  ]
}
```

***

## Get Protocol by Name and Chain

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/protocols/by-name/:name/chain/:chainId`

Retrieve all versions of a protocol on a specific chain.

### Request

```bash theme={null}
curl "https://api.1tx.fi/api/v1/protocols/by-name/Aave/chain/8453"
```

### Path Parameters

| Parameter | Type   | Required | Description                                          |
| --------- | ------ | -------- | ---------------------------------------------------- |
| `name`    | string | Yes      | Protocol name (Aave, Compound, Morpho, Euler, Fluid) |
| `chainId` | number | Yes      | Chain ID                                             |

### Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Aave",
    "version": 3,
    "displayName": "Aave V3",
    "chainId": 8453,
    "protocolAddress": "0x...",
    "icon": "aave",
    "docsUrl": "https://docs.aave.com",
    "deprecated": false,
    "deprecationReason": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z"
  }
]
```

***

## Get Latest Protocol Version

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/protocols/by-name/:name/chain/:chainId/latest`

Retrieve the latest version of a protocol on a specific chain.

### Request

```bash theme={null}
curl "https://api.1tx.fi/api/v1/protocols/by-name/Aave/chain/8453/latest"
```

### Path Parameters

| Parameter | Type   | Required | Description   |
| --------- | ------ | -------- | ------------- |
| `name`    | string | Yes      | Protocol name |
| `chainId` | number | Yes      | Chain ID      |

### Response

Returns a single protocol object with the same fields as an item in [List All Protocols](#list-all-protocols). Unlike `GET /protocols/:id`, this endpoint does not include the related `instruments` array.

***

## Create Protocol

<span style={{color: '#EAB308', fontWeight: 'bold'}}>POST</span> `/protocols`

Add a new protocol version to the registry.

### Request Body

| Field             | Type   | Required | Description                 |
| ----------------- | ------ | -------- | --------------------------- |
| `name`            | string | Yes      | Protocol name (e.g. "Aave") |
| `version`         | number | Yes      | Protocol version number     |
| `displayName`     | string | Yes      | Human readable name         |
| `chainId`         | number | Yes      | Chain ID                    |
| `protocolAddress` | string | Yes      | Contract address            |
| `icon`            | string | No       | Icon identifier             |
| `docsUrl`         | string | No       | Documentation URL           |

```bash theme={null}
curl -X POST "https://api.1tx.fi/api/v1/protocols" \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aave",
    "version": 3,
    "displayName": "Aave V3",
    "chainId": 8453,
    "protocolAddress": "0x...",
    "icon": "aave",
    "docsUrl": "https://docs.aave.com"
  }'
```

### Response

Returns the created protocol object.

***

## Update Protocol

<span style={{color: '#EAB308', fontWeight: 'bold'}}>PUT</span> `/protocols/:id`

Update an existing protocol's details.

### Path Parameters

| Parameter | Type   | Required | Description   |
| --------- | ------ | -------- | ------------- |
| `id`      | string | Yes      | Protocol UUID |

### Request Body

Same fields as *Create Protocol*. All fields are optional.

***

## Delete Protocol

<span style={{color: '#EF4444', fontWeight: 'bold'}}>DELETE</span> `/protocols/:id`

Remove a protocol from the registry.

### Path Parameters

| Parameter | Type   | Required | Description   |
| --------- | ------ | -------- | ------------- |
| `id`      | string | Yes      | Protocol UUID |

***

## Deprecate Protocol

<span style={{color: '#EAB308', fontWeight: 'bold'}}>POST</span> `/protocols/:id/deprecate`

Mark a protocol as deprecated without deleting it.

### Path Parameters

| Parameter | Type   | Required | Description   |
| --------- | ------ | -------- | ------------- |
| `id`      | string | Yes      | Protocol UUID |

### Request Body

| Field    | Type   | Required | Description            |
| -------- | ------ | -------- | ---------------------- |
| `reason` | string | No       | Reason for deprecation |

***

## TypeScript Example

```typescript theme={null}
const BASE_URL = 'https://api.1tx.fi/api/v1';

interface Protocol {
  id: string;
  name: string;
  version: number;
  displayName: string;
  chainId: number;
  protocolAddress: string;
  icon?: string;
  docsUrl?: string;
  deprecated: boolean;
  deprecationReason?: string;
  createdAt: string;
  updatedAt: string;
}

// Get all protocols
async function getProtocols(chainId?: number): Promise<Protocol[]> {
  const params = chainId ? `?chainId=${chainId}` : '';
  const response = await fetch(`${BASE_URL}/protocols${params}`);
  return response.json();
}

// Get protocol by ID
async function getProtocol(id: string): Promise<Protocol> {
  const response = await fetch(`${BASE_URL}/protocols/${id}`);
  return response.json();
}

// Get latest protocol version
async function getLatestProtocol(
  name: string,
  chainId: number
): Promise<Protocol> {
  const response = await fetch(
    `${BASE_URL}/protocols/by-name/${name}/chain/${chainId}/latest`
  );
  return response.json();
}

// Usage
const protocols = await getProtocols(8453);
console.log(`Found ${protocols.length} protocols on Base`);

protocols.forEach((p) => {
  console.log(`${p.displayName}: ${p.protocolAddress}`);
  if (p.deprecated) {
    console.log(`  ⚠️ Deprecated: ${p.deprecationReason}`);
  }
});
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Instruments API" icon="fingerprint" href="/api-reference/endpoints/instruments">
    Query DeFi instruments
  </Card>

  <Card title="Chains API" icon="link" href="/api-reference/endpoints/chains">
    Get supported chains
  </Card>
</CardGroup>