# API and agents > Your own port, read by your own scripts and agents. A key reads what the screens show you and nothing else, and it cannot move a thing. Source: https://docs.getport.app/api/ A key reads your own port: the wallets, holdings, DeFi, perps, predictions, NFTs, PnL, ledger, briefing and alerts the screens show you, and nothing from anybody else’s account. It only reads, so nothing here can move funds, sign a transaction or change a setting. ## What your port is worth, from your terminal With a key in `PORT_API_KEY`, one request: ```sh curl -s https://getport.app/api/v1/port -H "Authorization: Bearer $PORT_API_KEY" ``` Everything is under `https://getport.app/api/v1`, answers JSON, and takes the key as a bearer token. The table the API is built from is also published as [`https://getport.app/api/v1/openapi.json`](https://getport.app/api/v1/openapi.json) (OpenAPI 3.1) and [`https://getport.app/api/v1/llms.txt`](https://getport.app/api/v1/llms.txt), and neither of those needs a key. Every answer comes from the same snapshot the screens read, as fresh as the last read of your wallets, and those built from a read say in `asOf` how old it is. Every price carries a `confidence`, and one below the bar is shown on its row and never summed into a total. The API is part of [Pro+](https://docs.getport.app/plans/free-and-pro/) and above. ## Getting a key Make one under [Settings, API access](https://getport.app/settings/api) in Port\_. - **It is shown once**, when it is made. We keep a hash and cannot show it again, so copy it then. A key starts `port_`. - **An account holds up to five live keys**, each with the expiry you pick: 30 days, 90 days (the default), a year or never. Revoked and expired keys do not count towards the five. Any key can be revoked from the same page, and revoking stops it at once. - **We email you whenever a key is made**, so a key you did not make is one you hear about. - **Resetting your password revokes every key**, as it signs out every session, because a reset is what you do when you think somebody else got in. Make new ones afterwards. - **A key only reads what we already hold**, unless you turn on its refresh switch when you make it. That lets it queue a fresh read of your wallets, up to 3 a day on Pro+ and Ultra (not on sale yet), and each one costs us provider calls, so it is off unless you say otherwise. - **Keep the key in `PORT_API_KEY`** and never paste it into a prompt. Every example on these pages reads it from there. Making a key needs Pro+ or above. If the account leaves that plan its keys are kept, answer `402` meanwhile, and work again the day the plan does. ## The envelope Every answer has the same shape, with the endpoint’s own answer in `data`. The four fields beside it are always present, and null or empty where the endpoint has nothing to put there: ``` { "data": { ... }, "asOf": "...", "notCounted": "...", "sources": [ ... ], "generatedAt": "..." } ``` - **`asOf`** is how old the answer is: the oldest wallet read behind `/port` and `/holdings`, the oldest venue read behind `/perps` and `/predictions`, the oldest account behind `/positions`. Null on those when a wallet has not been read yet or no single read time is behind the answer, and always null on the other endpoints (`/me`, `/wallets`, `/nfts`, `/pnl`, `/activity`, `/briefing`, `/alerts` and `/refresh`), which carry no read time of their own. - **`notCounted`** says in one sentence what the headline leaves out, the same sentence Port\_ prints under its own figures, because a total without its caveat misleads by omission. Only `/port` and `/holdings` carry it, and on those it is null when nothing is left out. Everywhere else it is null. - **`sources`** says what kind of price the answer rests on: `market` for a quote off the market, or a protocol’s own figure such as `oracle:venus` or `derived:aave-v3` for a receipt priced by what it redeems for. Each holding’s `price.source` says the same for its row. Only `/port` and `/holdings` fill it; everywhere else it is an empty list. - **`generatedAt`** is when the server put this answer together, on every endpoint. Amounts and USD figures are strings, never numbers, so nothing is rounded on the way to you. ## Which wallets an answer covers Port, holdings, positions, perps, predictions, NFTs and activity are about the wallets you own: watched wallets and wallets you have excluded are left out, as they are on those screens, and a refresh reads only the same wallets. PnL covers every wallet on the account, as the PnL screen does, and so does `walletCount` in `/api/v1/me`. `/api/v1/wallets` lists every wallet, each marked. ## Endpoints Each has its own page with the parameters, the notes a caller needs, the fields of `data` and an example. | Endpoint | What it answers | | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | [`GET /api/v1/me`](https://docs.getport.app/api/reference/me/) | Who the key belongs to, their tier, wallet count and limit, and the key itself. | | [`GET /api/v1/wallets`](https://docs.getport.app/api/reference/wallets/) | Every wallet on the account, with its group and nickname. | | [`GET /api/v1/port`](https://docs.getport.app/api/reference/port/) | The headline: net worth, its parts, the figure per wallet and what is not counted. | | [`GET /api/v1/holdings`](https://docs.getport.app/api/reference/holdings/) | Every holding row with its amount, its price and the confidence behind it, paged at 500. | | [`GET /api/v1/positions`](https://docs.getport.app/api/reference/positions/) | DeFi accounts: one protocol on one chain in one wallet, with what is inside it. | | [`GET /api/v1/perps`](https://docs.getport.app/api/reference/perps/) | Perp positions, orders and fills per venue, with when each venue was last read. | | [`GET /api/v1/predictions`](https://docs.getport.app/api/reference/predictions/) | Polymarket and Limitless positions grouped by event, with whether the chain agreed on each. | | [`GET /api/v1/nfts`](https://docs.getport.app/api/reference/nfts/) | NFTs at floor, with their own total, which is not in net worth. | | [`GET /api/v1/pnl`](https://docs.getport.app/api/reference/pnl/) | Trading profit from the ledger: realised and unrealised on swaps and fills, first in first out, with the open lots and what is missing. | | [`GET /api/v1/activity`](https://docs.getport.app/api/reference/activity/) | The ledger, newest first, paged. | | [`GET /api/v1/briefing`](https://docs.getport.app/api/reference/briefing/) | The daily briefing as the server wrote it. | | [`GET /api/v1/alerts`](https://docs.getport.app/api/reference/alerts/) | Alerts that have fired, newest first. | | [`POST /api/v1/refresh`](https://docs.getport.app/api/reference/refresh/) | Queues a fresh read of every wallet. Needs a key made with refresh allowed. | ## Rate limits | Plan | Requests a minute | Requests a day | Refreshes a day | | ----------------------- | ----------------- | -------------- | --------------- | | Pro+ | 300 | 25,000 | 3 | | Ultra (not on sale yet) | 600 | 100,000 | 3 | Free and Pro have no API. Every limit is per account, shared by every key, REST, MCP and every app you connect by signing in. A refresh has its own daily count on top, whichever door it comes through. Your PnL counts all of your history on every paid plan; `/activity` and the lists inside `/pnl` stop at your plan’s window, and say where in `viewableFrom`. `RateLimit-Limit` and `RateLimit-Remaining` give the count for whichever limit has less left, since that is the one that will refuse the next request first. They are on every answer, a `429` included. On a `401` or a `402` they count the limit per address below instead, because the account limits are only counted once a key has been accepted. They are not on `openapi.json` or `llms.txt`, and not on anything answered while our rate-limit cache is down, when nothing is counted at all. There is also a limit of 600 requests a minute from one address, counted before the key is checked, so a flood of made-up keys is refused cheaply. It is several accounts’ worth and never binds on one person. To see where you stand, [Settings, API access](https://getport.app/settings/api) shows today’s count against your daily limit, read from the same counter that refuses a call, and a chart of the last 30 UTC days split between the API and MCP, with which endpoints and tools were asked for and which key or app asked. The chart fills in within a minute or two of a call. We count which endpoint or tool was called, never its parameters or its answer. The windows are fixed rather than rolling: a minute is a clock minute, and a day is a UTC day, midnight to midnight. ## Errors A refusal is `{ error, message }`: `error` is a code to branch on and `message` a sentence for a person. ### 400 A query parameter the endpoint cannot read: `bad_cursor` on `/holdings` and `/activity` for a cursor that is not one the server handed out; `bad_day` on `/briefing` for a `day` that is not `YYYY-MM-DD`. ```sh { "error": "bad_cursor", "message": "That is not a page marker of ours. Ask for the first page."} ``` ```sh { "error": "bad_day", "message": "Give me a day as YYYY-MM-DD"} ``` ### 401 No key, a malformed one, or one that has been revoked or has expired. It carries a `WWW-Authenticate: Bearer` header. ```sh { "error": "unauthorised", "message": "Send a Port_ API key as a bearer token. Make one in Settings, API access."} ``` ### 402 The account's plan has no API: Pro+ and above have it. The key is kept, and works again the day the plan does. ```sh { "error": "upgrade_required", "message": "Agents, MCP and the API are on Pro+ and above."} ``` ### 403 `POST /api/v1/refresh` with a key made without the refresh switch. It is not charged to the refresh limit. ```sh { "error": "refresh_not_allowed", "message": "This key was made without refresh. Make one with it on, in Settings."} ``` ### 404 `not_found` for a path under `/api` that is not an endpoint. Under `/api/v1` the key and the limits are checked first, so a wrong path there without a key is a `401`. `/api/v1/briefing` also answers `404` with `no_briefing` when no briefing has been written yet, or none for the day asked, which is the normal answer for a new account rather than a fault. ```sh { "error": "not_found", "message": "No such endpoint"} ``` ### 429 Past a limit above, the per-address one included. `Retry-After` is the length of the window that counted, in seconds: 60 for the minute, 86400 for the day. Because the windows are fixed, the real wait is up to the end of the current window, which for the day is the next UTC midnight and can be much sooner than `Retry-After` says. ```sh { "error": "rate_limited", "message": "Too many requests. Slow down a little."} ``` ## Agents The same reads are an MCP server at `https://getport.app/mcp`. An agent connects by signing you in at getport.app, with no key, or with a key if it cannot sign in. [Build with AI](https://docs.getport.app/build-with-ai/) has the one command that connects every coding agent on your computer, and [the MCP page](https://docs.getport.app/api/mcp/) the block for each client. ## Changes The API’s own changelog, newest first, is [API changes](https://docs.getport.app/api/changes/). A response only ever gains fields, so read it with unknown fields allowed rather than validating against a closed shape.