# Motrix Download Protocols: HTTP, BitTorrent, Magnet, FTP, and SFTP Support

> Download files using Motrix with HTTP, FTP, SFTP, BitTorrent, and Magnet links. Explore comprehensive protocol support for all your download needs.

- Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix)
- Tags: api-reference
- Published: 2026-08-20

---

**Motrix supports six download protocols—HTTP/HTTPS, FTP, SFTP, BitTorrent (BT), Magnet links, and Metalink—defined in the `TuningContext` interface and accessible via the `addTask` plugin API.**

Motrix is a full-featured open-source download manager maintained by agalwood that handles diverse file transfer protocols through a unified engine. Understanding the supported Motrix download protocols helps developers leverage its capabilities for standard web transfers, peer-to-peer networks, and secure file transfers. The protocol definitions reside in the core type system, specifically within the `TuningContext` interface located in the source code.

## Complete List of Supported Motrix Download Protocols

The `protocol` field in the `TuningContext` type at [`src/shared/types/tuning.ts`](https://github.com/agalwood/Motrix/blob/main/src/shared/types/tuning.ts) (line 30) enumerates the following supported values:

- **http** – Handles both standard HTTP and encrypted HTTPS URLs through a single generic handler
- **ftp** – Standard File Transfer Protocol for traditional file transfers  
- **sftp** – SSH File Transfer Protocol for encrypted, secure transfers
- **bt** – BitTorrent protocol for downloading via `.torrent` metadata files
- **magnet** – Magnet URI scheme for BitTorrent downloads without requiring a .torrent file
- **metalink** – XML-based Metalink files containing multiple mirrors and file checksums

## Protocol Definitions in the Source Code

In [`src/shared/types/tuning.ts`](https://github.com/agalwood/Motrix/blob/main/src/shared/types/tuning.ts), the `TuningContext` interface centralizes protocol information used for performance-tuning and download-strategy decisions. This interface constrains the allowed values for the `protocol` field, which the download engine uses to determine routing logic and connection handling parameters.

Task validation occurs in [`src/shared/schemas/add-task.ts`](https://github.com/agalwood/Motrix/blob/main/src/shared/schemas/add-task.ts), where protocol-specific payloads are validated against strict schemas before submission to the download engine.

## Adding Downloads by Protocol

Motrix exposes these protocols through the `addTask` function from the `motrix:plugin-api` module. Each protocol requires a specific payload structure when creating new download tasks.

### HTTP and HTTPS Downloads

For standard web downloads, Motrix treats the `http` protocol value as a generic handler that accepts both `http://` and `https://` schemes.

```typescript
import { addTask } from 'motrix:plugin-api';

// Simple HTTP/HTTPS URL
await addTask({
  url: 'https://example.com/file.zip',
  // Additional optional fields (download path, etc.) can be provided
});

```

### BitTorrent (.torrent) Files

To initiate a BitTorrent download using a local `.torrent` file, provide base64-encoded torrent data along with metadata.

```typescript
import { addTask } from 'motrix:plugin-api';

// Provide the base64-encoded torrent file
await addTask({
  tab: 'torrent',
  torrentMeta: {
    name: 'ubuntu-22.04.iso',
    files: [{ path: 'ubuntu-22.04.iso', length: 3000000000 }],
    // …other metadata fields
  },
  torrentBase64: 'BASE64_ENCODED_TORRENT_DATA',
});

```

### Magnet Links

Magnet URIs enable torrent downloads without distributing `.torrent` files, using distributed hash table (DHT) lookup.

```typescript
import { addTask } from 'motrix:plugin-api';

// Magnet URI
await addTask({
  magnet: 'magnet:?xt=urn:btih:ABCDEF1234567890...',
});

```

### Metalink Files

Metalink downloads utilize XML descriptors that specify multiple mirrors and cryptographic checksums for verification.

```typescript
import { addTask } from 'motrix:plugin-api';

// Metalink XML (as a string)
await addTask({
  url: 'https://example.com/file.metalink',
});

```

## Summary

- Motrix supports **six protocols**: HTTP/HTTPS, FTP, SFTP, BitTorrent, Magnet, and Metalink
- Protocol definitions reside in the **`TuningContext`** interface at [`src/shared/types/tuning.ts`](https://github.com/agalwood/Motrix/blob/main/src/shared/types/tuning.ts)
- The **`addTask`** function from `motrix:plugin-api` handles all protocol types with specific payload requirements
- **HTTP** protocol handler covers both unencrypted and TLS-encrypted transfers transparently
- **BitTorrent** requires base64-encoded file data while **Magnet** links use URI strings directly
- **Metalink** files are processed via standard URL references to XML descriptors

## Frequently Asked Questions

### Does Motrix support HTTPS downloads?

Yes. While the `TuningContext` protocol enum lists `http` in [`src/shared/types/tuning.ts`](https://github.com/agalwood/Motrix/blob/main/src/shared/types/tuning.ts), Motrix treats this as a generic HTTP handler that accepts both `http://` and `https://` URLs. The underlying engine automatically handles TLS encryption when parsing HTTPS links through the `addTask` API.

### Can Motrix download magnet links without .torrent files?

Yes. The `magnet` protocol value exists independently from the `bt` protocol in the `TuningContext` type. You can pass magnet URIs directly to the `addTask` function using the `magnet` property, without requiring base64-encoded torrent data or local `.torrent` files.

### What is the difference between BT and Magnet protocols in Motrix?

The `bt` protocol requires a `.torrent` file provided as base64-encoded data via the `torrentBase64` field and `tab: 'torrent'` specification, while the `magnet` protocol accepts a `magnet:` URI string in the `magnet` field. Both utilize BitTorrent peer-to-peer networking, but `bt` includes complete metadata in the initial request, whereas `magnet` retrieves metadata from the swarm.

### How does Motrix validate protocol-specific download tasks?

Task validation occurs in [`src/shared/schemas/add-task.ts`](https://github.com/agalwood/Motrix/blob/main/src/shared/schemas/add-task.ts), which enforces protocol-specific schemas before submission. This validation ensures HTTP URLs, torrent metadata structures, magnet URI formats, and metalink files conform to required payloads before the download engine processes them.