Skip to content
Build with AI

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.

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

Section titled “What your port is worth, from your terminal”

With a key in PORT_API_KEY, one request:

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 (OpenAPI 3.1) and 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+ and above.

Make one under Settings, API access 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.

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.

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.

Each has its own page with the parameters, the notes a caller needs, the fields of data and an example.

EndpointWhat it answers
GET /api/v1/meWho the key belongs to, their tier, wallet count and limit, and the key itself.
GET /api/v1/walletsEvery wallet on the account, with its group and nickname.
GET /api/v1/portThe headline: net worth, its parts, the figure per wallet and what is not counted.
GET /api/v1/holdingsEvery holding row with its amount, its price and the confidence behind it, paged at 500.
GET /api/v1/positionsDeFi accounts: one protocol on one chain in one wallet, with what is inside it.
GET /api/v1/perpsPerp positions, orders and fills per venue, with when each venue was last read.
GET /api/v1/predictionsPolymarket and Limitless positions grouped by event, with whether the chain agreed on each.
GET /api/v1/nftsNFTs at floor, with their own total, which is not in net worth.
GET /api/v1/pnlTrading 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/activityThe ledger, newest first, paged.
GET /api/v1/briefingThe daily briefing as the server wrote it.
GET /api/v1/alertsAlerts that have fired, newest first.
POST /api/v1/refreshQueues a fresh read of every wallet. Needs a key made with refresh allowed.
PlanRequests a minuteRequests a dayRefreshes a day
Pro+30025,0003
Ultra (not on sale yet)600100,0003

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 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.

A refusal is { error, message }: error is a code to branch on and message a sentence for a person.

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.

{ "error": "bad_cursor", "message": "That is not a page marker of ours. Ask for the first page."}
{ "error": "bad_day", "message": "Give me a day as YYYY-MM-DD"}

No key, a malformed one, or one that has been revoked or has expired. It carries a WWW-Authenticate: Bearer header.

{ "error": "unauthorised", "message": "Send a Port_ API key as a bearer token. Make one in Settings, API access."}

The account's plan has no API: Pro+ and above have it. The key is kept, and works again the day the plan does.

{ "error": "upgrade_required", "message": "Agents, MCP and the API are on Pro+ and above."}

POST /api/v1/refresh with a key made without the refresh switch. It is not charged to the refresh limit.

{ "error": "refresh_not_allowed", "message": "This key was made without refresh. Make one with it on, in Settings."}

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.

{ "error": "not_found", "message": "No such endpoint"}

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.

{ "error": "rate_limited", "message": "Too many requests. Slow down a little."}

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 has the one command that connects every coding agent on your computer, and the MCP page the block for each client.

The API’s own changelog, newest first, is API changes. A response only ever gains fields, so read it with unknown fields allowed rather than validating against a closed shape.