Setup & Troubleshooting

Xtream Codes explained: what the IPTV login is, how the API works, and what its errors mean

By Henry Hopkins · Reviewed by IPTV Americans Editorial Team · Published September 13, 2026 · Updated September 13, 2026 · 22 min read

What is Xtream Codes?

Xtream Codes is a way of logging an IPTV player into a subscription. Instead of pasting one long playlist address, you enter three separate details your provider issued — a server URL, a username and a password — and the player uses them to ask the provider's server for everything else: the live channel list, the movie and series libraries, the programme guide, and the status of your account.

The name refers to an API — a fixed set of addresses and responses that a player and a server both understand. That shared language is the whole point. A provider running a compatible server and a player that supports the format can work together without either knowing anything else about the other, which is why the same three credentials work in TiviMate, IPTV Smarters Pro and many other players.

Two things Xtream Codes is not, because both get confused constantly:

• It is not an IPTV service. It describes how the login works, not who supplies the channels. Every channel, programme listing and film arrives from your provider's servers. The player — and the login format — contain no content at all.
• It is not the company of the same name. Xtream Codes Ltd, which built the original software, stopped operating in 2019. The login format outlived it, which is why you still see the option in players today. The history section covers what happened, including a court ruling most accounts leave out.

Our glossary entry for Xtream Codes gives the one-line definition. This page covers the mechanism: what the three details actually do, what the server sends back, how it compares with an M3U playlist, and how to read the errors.

The three details your provider gives you

An Xtream Codes login always comes as the same three pieces, usually in an activation email or message:

The server URL has three parts, and each one matters. The protocol is http:// or https://. The host is the server's name. The port is the number after the colon. Many providers run on a non-standard port, and if you leave it off, the player knocks on a door nobody is answering.

The entry mistakes behind most failed logins

When a login fails, the details are usually almost right. These account for the large majority of failures that turn out not to be anything wrong with the account:

• Leaving off the port. http://your-provider-host and http://your-provider-host:8080 are different addresses.
• The wrong protocol. Entering https:// for a server that only answers on http://, or the reverse, fails at the connection stage before your username is even checked.
• Pasting a whole playlist URL into the server field. The server field wants only the protocol, host and port. Anything after that — /get.php?username=…, /player_api.php or a trailing path — belongs to a different kind of setup.
• Invisible characters. A space copied at the start or end of the username or password is a different username or password.
• Autocorrect. Phones and some TV keyboards capitalise the first letter of the username without asking. Most Xtream Codes servers treat usernames and passwords as case-sensitive.
• Lookalike characters. A capital O against a zero, or a lowercase l against the number one, in a font that makes them identical.

The fix for nearly all of these is the same: copy and paste each detail from the activation message instead of typing it. On a TV, where pasting is rarely possible, enter each detail slowly and compare it with the activation message character by character before you submit. Two minutes of checking beats twenty minutes of troubleshooting a typo.

How the Xtream Codes API works

When you press log in, the player does not download one big file. It holds your credentials and makes a series of short, specific requests to the server, each asking for one piece of the picture. That design is what separates Xtream Codes from a plain playlist, and it explains almost every behaviour you will notice.

Step 1: the login check

The first request goes to an address ending in player_api.php, with your username and password attached:

http://your-provider-host:8080/player_api.php?username=USERNAME&password=PASSWORD

The server replies with a small block of JSON describing your account and the server itself. A trimmed, anonymised example looks like this:

{
  "user_info": {
    "username": "USERNAME",
    "auth": 1,
    "status": "Active",
    "exp_date": "1798761600",
    "is_trial": "0",
    "active_cons": "1",
    "max_connections": "2",
    "allowed_output_formats": ["m3u8", "ts"]
  },
  "server_info": {
    "url": "your-provider-host",
    "port": "8080",
    "https_port": "8443",
    "server_protocol": "http",
    "timezone": "America/New_York"
  }
}

The field that decides everything is auth. A 1 means the server recognised the credentials. A 0 — or a reply with no account details in it at all — means it did not. Exact field names and formats vary slightly between server panels, so treat this as the shape rather than a byte-exact specification.

Step 2: fetching the catalogue in sections

Once the login is accepted, the player goes back to the same player_api.php address with an extra action telling the server what it wants next. Live channel groups, then the channels in them. Movie categories, then the films. Series, then seasons and episodes when you open one. Each is its own request with its own response.

This is why a first load can take a minute on a large subscription, and why the parts can fail independently. The live list can arrive while the series library does not. It is also why a manual update playlist in the player fixes more problems than reinstalling does: it re-runs these requests without throwing away your settings.

Step 3: building each stream address

The channel list does not contain ready-made video links. It contains an ID for each channel, and the player assembles the stream address itself when you press play, from the server URL, your credentials and that ID:

http://your-provider-host:8080/live/USERNAME/PASSWORD/12345.ts

Movies and series episodes follow the same pattern under /movie/ and /series/, ending in the file's own extension. The ending on a live address — .ts for an MPEG-TS stream or .m3u8 for HLS — is the stream format. The allowed_output_formats field in the login reply is the server telling the player which ones it will serve. That field is behind a useful fix covered in the errors section.

Step 4: the programme guide

The guide comes from the same login but through a separate address, xmltv.php, which returns the full schedule as an XMLTV file. There is also a per-channel get_short_epg action that players use to fill in now-and-next quickly. The guide being a separate feed is why channels can play while the grid sits empty. That problem has its own page: our IPTV EPG guide covers how the schedule is built, matched to channels and fixed.

The Xtream Codes endpoints at a glance

You never need to type these into a player — it builds them for you. They are listed here because knowing them makes support conversations and self-testing far quicker. USER and PASS stand for your own credentials.

Every row except the last three uses the same starting address: http://your-provider-host:8080/ followed by the file name, with ?username=USER&password=PASS attached and, for the player_api.php rows, &action=… after it.

Notice the get.php row. An M3U playlist from an Xtream Codes provider is usually generated from the same account through that address. The two methods are not rival systems. They are two doors into the same account, which leads straight to the most practical question.

Xtream Codes vs M3U: which should you use?

Use Xtream Codes when your provider offers it. An M3U URL is a perfectly good fallback, but it is the less capable of the two for everyday viewing. An M3U playlist is a single text file listing channels and their stream addresses. Xtream Codes is a live conversation with the server, and that difference shows up in everything a player can do.

When M3U is the better choice

There are real cases for it. Use an M3U URL when your player does not offer an Xtream Codes option at all, when you only want live channels in a general-purpose media player, or when you are deliberately building one custom list from a trimmed-down playlist. Some set-top boxes and older apps only accept M3U, and for live TV alone that is completely adequate.

The one thing to expect when you choose M3U is a smaller picture: channels without the on-demand library, and a guide you may have to add by hand. If you switched to M3U and your movies disappeared, that is why — not a fault with your subscription.

Xtream Codes vs a MAC or Stalker portal

You may see a third option on some devices, particularly MAG set-top boxes: a portal URL that authenticates by your device's MAC address instead of a username and password. That is a different system with different behaviour. Our glossary entry on Stalker Portal explains it. If your provider offers both and your device supports Xtream Codes, the login is generally the easier of the two to move between devices.

What your player can read about your account

The login reply is why players can show your account details without your provider building anything specially for them. The fields worth knowing:

• status — typically Active, Expired, Banned or Disabled. Anything other than Active explains a failing login instantly.
• exp_date — the expiry as a Unix timestamp, a count of seconds since 1 January 1970. The 1798761600 in the example above is midnight UTC on 1 January 2027. Players convert it into a readable date for you. An empty value usually means no expiry is set.
• max_connections — how many streams the account may run at the same time.
• active_cons — how many streams are running right now. When this reaches max_connections, new playback is refused.
• is_trial — whether this is a trial account, which often carries a lower connection limit or a short expiry.

Because this comes straight from the provider's server, the expiry your player displays is the provider's own record. If it differs from the date you remember, the player is not wrong; it is the one to raise with your provider.

Xtream Codes errors and what they actually mean

Most error messages here are the player accurately passing on what the server said, or reporting that the server never answered. The first diagnostic question is always the same: does the channel list load at all? If it does, your credentials are fine, and the problem is further along.

"Invalid credentials" when the details are definitely right

This is the most frustrating version, and it has a short list of causes. Some players show the same generic login failure for an expired or disabled account as for a typo, so a correct password can still produce it. The server URL may also have changed — providers occasionally move to a new host and send the new address in a notice that is easy to miss. The self-test below separates these in under a minute, because the raw reply tells you exactly which it is.

Why switching the stream format fixes some playback failures

Most players let you choose the stream format — often labelled MPEG-TS and HLS, or .ts and .m3u8. The server only serves the formats listed in allowed_output_formats, and devices differ in how well they handle each one. When channels load but will not start, or start and stall immediately, switching format is a quick, reversible test that isolates a device-side playback problem from a stream-side one. If neither format plays any channel, the issue is not the format; see our IPTV troubleshooting guide for the wider diagnostic path.

"Max connections" when nobody else is watching

The server counts open streams, not people. A player left running in the background on another device, a TV that was switched off at the wall mid-stream, or a phone that lost connection without closing the stream properly can all hold a connection open for a short time. Waiting a minute or two usually releases it. If the limit is reached repeatedly with no other devices in use, the credentials may have been shared or leaked — which is a reason to ask your provider for a new password, covered under keeping your login private.

Test your Xtream Codes login yourself

You can see exactly what the server says about your account, which settles most "is it me or them?" questions immediately. On any computer with a terminal, on the same network as your TV, run the login request directly:

curl -s "http://your-provider-host:8080/player_api.php?username=USER&password=PASS"

Then read the reply:

• "auth":1 with "status":"Active" — your account is working. The problem is in the player, the device or the network.
• "auth":0, or no user_info at all — the server did not accept these credentials. Recheck them character by character.
• A status other than Active — expired, banned or disabled. The reply has told you the cause.
• No reply, or a connection error — the server URL, port or protocol is wrong, or the network is blocking the connection. Credentials have not been checked yet.

Two cautions. The command puts your password in your terminal history, so do not run it on a shared or work computer. And never paste your login into an online "IPTV checker" website to test it — that hands your subscription to a stranger, which is the subject of the next section.

Keeping your Xtream Codes login private

Anyone who has your server URL, username and password has your subscription. There is no second factor and no device pairing. That makes a few habits worth adopting:

• Treat any URL containing your credentials as a password. Stream addresses and M3U links carry your username and password in plain text inside the address itself. Crop them out of screenshots and do not paste them into forums when asking for help.
• Assume the connection is not encrypted. Many servers use plain http://, so credentials travel unencrypted. Avoid logging in on public Wi-Fi you do not trust.
• Do not share the login outside your household. Sharing pushes the account into its connection limit, and providers routinely disable accounts that show use from many locations.
• If your details leak, ask for a reset. A new password invalidates every copy of the old one.

What "free Xtream Codes" lists actually are

Searches for this topic turn up a steady supply of posted usernames and passwords. A working one is either somebody else's paid account or an unauthorised one. It stops without warning when the owner changes the password or the provider disables it, it collides with that account's connection limit, and there is no telling what server you are connecting to or who is logging your traffic. The only credentials worth using are the ones your own provider issued to you.

Where to enter Xtream Codes in your player

The option has slightly different names from app to app, but it is always in the add-playlist or login screen, and it always asks for the same three details. Look for any of these labels:

• TiviMate — Add playlist, then Xtream Codes. Full walkthrough in our TiviMate setup guide.
• IPTV Smarters Pro — Login with Xtream Codes API. Step by step in our IPTV Smarters Pro guide.
• Other players — often labelled Xtream Codes API, XC, or simply a login form with server, username and password fields.

If a player offers only an M3U option, you can still use your subscription through an M3U URL, with the trade-offs in the comparison above. For device-specific install steps before you reach the login screen, start with our Firestick guide.

Where the name came from: the 2019 shutdown and the 2021 ruling

Almost every page on this topic either skips the history or gets it half right. The accurate version is worth knowing, because it explains why the name still appears in players, and it draws a line that matters.

The company and its software

Xtream Codes began as the name of a company, Xtream Codes Ltd, whose management software let IPTV operators run services: handling customer accounts, connection limits and the delivery of streams through a standard API. The software itself supplied no content. What flowed through it depended entirely on the operator using it.

September 2019: the shutdown

In September 2019, a coordinated operation led from Naples, involving Italy's Guardia di Finanza and coordinated through the EU agency Eurojust, took the platform offline, with raids and server seizures in several European countries. Many IPTV services built on it went dark overnight. The scale reported at the time varied considerably between accounts — figures ranged from hundreds of thousands of direct customers to claims of tens of millions of end users — and TorrentFreak's coverage that week questioned how some of those totals had been reached.

August 2021: the appeals court

The part most accounts leave out came later. According to TorrentFreak's June 2022 report, on 3 August 2021 the Court of Appeals of Naples found no evidence that Xtream Codes Ltd had acted illegally at any point between its start in 2015 and its closure in 2019. The court found that the company's revenue had been counted by adding up all of its invoices rather than by showing any of it came from illegal activity, and the seized revenue was released. The prosecutor's appeal to Italy's Supreme Court of Cassation was dismissed.

What that ruling does and does not mean

The ruling concerns the company and its software. It says nothing about whether any IPTV service that used the software — then or now — had the rights to what it streamed. That is the same distinction that runs through every player page on this site: the software is not the content. A login format tells you how a player connects; it tells you nothing about whether the service on the other end is licensed. Our guide to legal IPTV services covers how to tell the difference.

Sources

• TorrentFreak, 16 June 2022 — Xtream-Codes IPTV company declared lawful, assets seized in raid returned
• TorrentFreak, 19 September 2019 — The Xtream Codes IPTV takedown is complex and confused
• TorrentFreak, 9 January 2020 — Xtream-Codes: we have nothing to do with resurrected IPTV system Xtream UI

What "Xtream Codes" means today

When a player offers an Xtream Codes option today, it means the API format — not the company, and not any connection to it. After the 2019 shutdown, other server software appeared that speaks the same player_api.php language, and players kept the familiar label because it told users exactly which three details to enter. Xtream Codes Ltd itself publicly stated, in January 2020, that it had nothing to do with Xtream UI, one of the projects that emerged afterwards using a similar approach.

The practical upshot for a viewer is simple. The name on the login screen describes the shape of the login. The server behind it belongs to whichever provider issued your credentials, and everything about the quality, reliability and lawfulness of the service comes from that provider rather than from the format.

That is also the right lens for choosing one. A provider that issues Xtream Codes credentials is not better or worse for doing so. What matters is what sits behind the login: whether channels stay up on the nights that matter, whether the guide is complete, whether broken streams get fixed when reported, and whether the service is honest about what it carries. Our guide to choosing an IPTV service works through those questions.

Quick reference: Xtream Codes terms in one place

Frequently asked