The eccuity API

Overview

The API is available to anyone on a paid eccuity plan who wants to connect an external tool to their account: a personal script, a spreadsheet, an AI assistant, or a full third-party app that other eccuity users could also connect to. Free accounts can authenticate for basic sign-in purposes only, but can't grant a token access to portfolio, trading, or funding data.

Every operation requires a specific scope, and a token can only do what it was explicitly granted, regardless of what your account can otherwise do. GraphQL introspection is disabled in production, so the full reference below, generated from the live schema, is the source of truth for argument and return shapes.

Use cases

A sample of what people build on top of the API, from inside eccuity and out.

Quick start

The fastest way to make your first authenticated call, no redirect flow, no consent screen, is a server-to-server (client credentials) credential. Right for a personal script or backend service acting on your own account.

1. 1.Log into the eccuity app and go to Settings → API Credentials.
2. 2.Click New credential. Give it a label. Leave “Public client (PKCE)” unchecked.
3. 3.Copy the Client ID and Client Secret shown. The secret is shown once, and can't be retrieved again.
4. 4.Exchange them for an access token. Your exact API base URL is shown on the Settings → API Credentials page.
   bash

   curl -X POST https://api.<your-eccuity-domain>/oauth/token \
     -u "ecc_id_xxxxxxxx:ecc_sk_xxxxxxxx" \
     -d "grant_type=client_credentials" \
     -d "scope=full_access"

   Response:

   json

   {
     "access_token": "ecc_at_xxxxxxxxxxxxxxxx",
     "token_type": "Bearer",
     "expires_in": 3600,
     "scope": "identity profile.read profile.write portfolio.read portfolio.write trade funding.read funding.write"
   }

5. 5. Call the API with the token, a Bearer token good for one hour.
   bash

   curl -X POST https://api.<your-eccuity-domain>/graphql \
     -H "Authorization: Bearer ecc_at_xxxxxxxxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{"query": "query { fetchCurrentUser { id name email } }"}'

Authentication

eccuity's API is a standard OAuth 2.0 authorization server, with two flows depending on what you're building. Both end the same way: a Bearer access token sent as Authorization: Bearer <token> on every request.

POST /oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=full_access

Scopes

Every operation requires a specific scope. Your token can only call an operation if it was granted that scope, or a composite scope that includes it: a token can do no more than you can do yourself, but you can hand out a token that does less. Space-separate multiple scopes (e.g. scope=portfolio.read trade). Unknown scope names are rejected outright.

Composite (shortcut) scopes

A few operations exist only for the eccuity app itself and are never reachable with a Bearer token, regardless of scope: managing your own API credentials, and the OAuth consent screen's own internal fields. These return a FORBIDDEN error naming the field.

Full reference

Every operation, argument, and return type, generated straight from the live schema so it never drifts from what the API actually accepts.

A handful of operations are subscriptions: long-lived, pushed updates (live prices, news, export job status, AI assistant streaming) over a WebSocket connection rather than a plain POST. Use a GraphQL client that supports graphql-ws (e.g. Apollo Client, urql) and authenticate the socket with your Bearer token.

Example requests

query {
  netWorthDashboard {
    totals {
      netWorth
      totalAssets
      totalLiabilities
      totalMonthlyExpenses
      totalAnnualIncome
    }
    assets { id }
    liabilities { id }
    goals { id }
    incomes { id }
    expenses { id }
  }
}

mutation {
  placeOrder(params: {
    assetId: "..."
    brokerCredentialId: "..."
    side: BUY
    type: MARKET
    quantity: 10
    notional: 0
    limitPrice: 0
    stopPrice: 0
    premarket: false
    timeInForce: DAY
  }) {
    id
    status
    quantityFilled
    averageFilledPrice
  }
}

query {
  getPositions(params: { tradingMode: "LIVE" }) {
    symbol
    quantity
    averageEntryPrice
    marketValue
    unrealizedProfitLoss
  }
}

Errors

Errors follow the standard GraphQL error shape:

{
  "errors": [
    {
      "message": "This token is missing the required scope \"trade\" for: placeOrder",
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

Rate limits

• 50 requests/second per authenticated user (or per IP if unauthenticated) across the API generally.
• 5 requests/second on sensitive endpoints (login, token issuance, password reset, MFA): /oauth/token falls under this stricter limit.

Rate-limit headers (Rate-Limit-Remaining, Rate-Limit-Reset, Rate-Limit-Total) are returned on every response so you can back off proactively.

Good practices

• Request only the scopes you need. A token is a bearer credential: anyone who obtains it can act as you, within its scopes. Don't request full_access for a script that only reads net worth data.
• Treat the client secret like a password. It's shown once at creation time and never retrievable again. If you lose it, delete the credential and create a new one.
• Expect 1-hour tokens. Build your integration to request a fresh token when a call fails with an auth error, rather than assuming long-lived access.
• Delete unused credentials. Each one is a live door into your account; Settings → API Credentials shows last-used time and IP so you can spot anything that shouldn't still be active.
• One credential per integration. Makes it easy to revoke a single integration without breaking everything else.