Skip to content

REST · MCP · A2A

Connect your agent

Give your agent a scoped API key, choose REST, MCP or A2A, and check the connection before it spends.

Create your account, then add at least $1,000 in Stripe Checkout. Your confirmed payment goes directly to your wallet.

The full amount is available for research.

No sales approval or Altss subscription required. No subscription or automatic reload.

Review API and MCP setup

How to use Console

  1. 1. Fund your wallet

    After signup, add at least $1,000 to your wallet through Stripe Checkout.

    Add funds
  2. 2. Create a scoped key

    After your payment clears, select Create agent key for SEC financial research. The key includes the company.read scope and spending limits. You can also choose your own settings.

    Connect your agent
  3. 3. Track the work

    Agents retrieve their run’s result and receipt. Your team follows execution, usage and balance in Console.

    View activity

Sign in to manage your keys and activity. Each paid run draws on your available wallet balance.

REST: check your connection

Store your key as ALTSS_AGENT_KEY in your secret manager or environment. Listing tools does not start a paid execution.

curl --fail-with-body https://console.altss.com/v1/console/tools \
  -H "Authorization: Bearer $ALTSS_AGENT_KEY"

A successful response lists the tools this organization can use. A 401 means the credential or channel is not accepted; 403 means current organization or consent requirements are not met.

MCP: connect your client

Use a credential with the MCP channel. This is a Streamable HTTP configuration for clients supporting custom Authorization headers; client configuration formats vary.

Claude Code

claude mcp add --transport http altss https://console.altss.com/v1/console/mcp \
  --header "Authorization: Bearer $ALTSS_AGENT_KEY"

Run it where ALTSS_AGENT_KEY is set; Claude Code saves the header in your local configuration. Then run /mcp in Claude Code to confirm the connection.

Other clients

{
  "mcpServers": {
    "altss": {
      "type": "http",
      "url": "https://console.altss.com/v1/console/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ALTSS_AGENT_KEY>"
      }
    }
  }
}

Replace the placeholder locally. Keep credentials out of chat, shared configuration and URLs. This deployment also accepts MCP clients that use OAuth authorization code with PKCE (S256) and a public HTTPS client metadata document as their client ID, after your explicit approval; the resulting credential is limited to MCP and expires within an hour. Dynamic client registration, client secrets and refresh tokens are not supported. Agents may also use the user-claimed service_auth flow after your explicit approval. Follow the authorization guide for the supported flows, scopes and spending authority. Anything else needs a key you create in Console.

A2A: connect an agent-to-agent client

A2A clients discover Console from its public agent card, then send JSON-RPC messages with the same Bearer key (API channel) that REST uses. Every executable capability appears as a skill on the card. A2A shares the quote, wallet, spending limits and receipts of REST and MCP.

Agent card
https://console.altss.com/.well-known/agent-card.json
JSON-RPC endpoint
https://console.altss.com/v1/console/a2a
Authorization
Authorization: Bearer $ALTSS_AGENT_KEY, plus the header A2A-Version: 1.0.
Skills on the card
8

Read the agent card

curl https://console.altss.com/.well-known/agent-card.json

Request a quote (SendMessage)

curl https://console.altss.com/v1/console/a2a \
  -H "Authorization: Bearer $ALTSS_AGENT_KEY" \
  -H "A2A-Version: 1.0" \
  --json '{"jsonrpc":"2.0","id":"1","method":"SendMessage","params":{"message":{"messageId":"msg-1","role":"ROLE_USER","parts":[{"data":{"toolId":"company.financial_research","input":{"cik":"0000789019"}},"mediaType":"application/json"}]}}}'

A message carrying only a toolId and input returns a quote and never spends money. To buy one result, send the unchanged quote back in the data part with accept set to true and a stable idempotencyKey; reuse that key on retries. Poll the returned task with GetTask. Authentication alone does not authorize payment.

Quote → authorize → execute → retrieve

Your agent can perform these steps within the spending authority your organization grants. Authentication alone does not authorize payment. Validate the returned tool, scope, price, expiry and allowed use before accepting the complete quote.

curl https://console.altss.com/v1/console/quote \
  -H "Authorization: Bearer $ALTSS_AGENT_KEY" \
  --json '{"toolId":"company.financial_research","input":{"cik":"0000789019"}}' > quote.json
Purchase request — uses prepaid funds

Run only after authorizing this quote. Set a unique ALTSS_PURCHASE_ID once per purchase and reuse it on retries; do not blindly regenerate it.

# After reviewing quote.json and authorizing the displayed price:
jq -n --slurpfile quote quote.json \
  '{toolId:"company.financial_research", input:{cik:"0000789019"}, quote:$quote[0], accept:true}' > purchase.json
curl https://console.altss.com/v1/console/runs \
  -H "Authorization: Bearer $ALTSS_AGENT_KEY" \
  -H "Idempotency-Key: $ALTSS_PURCHASE_ID" \
  --json @purchase.json
# Persist a unique ALTSS_PURCHASE_ID per purchase. Reuse it on retries.

Keep the returned runId. GET /v1/console/runs/<runId> retrieves status and the settled result and receipt without purchasing again. MCP exposes altss_list_capabilities, altss_quote, altss_run and altss_get_run; send protocol version 2025-06-18.

Replace and revoke keys

Secrets are shown once. To replace one, create a replacement with the required scopes, channels and limits, update your agent, test the replacement, then revoke the old credential. Revocation refuses its next call; already reserved work settles normally.

Manage API keys

Deliver to your workflow

Retrieve completed results over REST, MCP and A2A and let your own authorized agent route permitted output to your systems. Built-in Slack delivery, outbound webhooks and scheduled monitoring are not available in this release.

Read the agent integration reference

Reference

What comes back

Abridged shapes with placeholder values. A quote reads no company data and charges nothing; the run returns the purchased result together with its receipt.

Quote response

{
  "quoteId": "q_<40 hex characters>",
  "toolId": "company.financial_research",
  "toolVersion": 1,
  "currency": "usd",
  "priceMinor": 2500,
  "maxReserveMinor": 2500,
  "issuedAt": "<timestamp>",
  "expiresAt": "<15 minutes after issuedAt>",
  "useTerms": {
    "…": "permitted uses, storage, caching, retention, attribution, training limits"
  },
  "plan": {
    "…": "bounded plan: one tool call, 25 second timeout"
  }
}

Settled run response

{
  "runId": "<uuid>",
  "receiptId": "<uuid>",
  "tool": {
    "id": "company.financial_research",
    "version": 1
  },
  "result": {
    "issuer": {
      "cik": "0000789019",
      "reportedName": "…"
    },
    "periods": [
      {
        "start": "…",
        "end": "…",
        "filingUrl": "…",
        "facts": [
          {
            "metric": "…",
            "unit": "USD",
            "value": "…",
            "form": "…"
          }
        ],
        "derived": {
          "…": "labeled derived comparisons"
        }
      },
      {
        "…": "the second adjacent annual period"
      }
    ],
    "limitations": [
      "…"
    ]
  },
  "usage": {
    "settledMinor": 2500,
    "releasedMinor": 0,
    "balanceAfterMinor": "…"
  },
  "receipt": {
    "…": "sealed settlement receipt"
  },
  "replayed": false
}

Retrieve a run again without charging

curl --fail-with-body https://console.altss.com/v1/console/runs/$RUN_ID \
  -H "Authorization: Bearer $ALTSS_AGENT_KEY"

MCP tool calls

The tools are altss_list_capabilities, altss_quote, altss_run and altss_get_run. altss_list_capabilities is free and read-only: call it first. altss_quote, altss_run and altss_get_run take the same arguments as the REST bodies. Once connected, an MCP client sends calls like this one.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "altss_quote",
    "arguments": {
      "toolId": "company.financial_research",
      "input": {
        "cik": "0000789019"
      }
    }
  }
}

Send Content-Type: application/json, Accept: application/json, text/event-stream and MCP-Protocol-Version: 2025-06-18. A failed tool call is HTTP 200 with result.isError true, so check both the HTTP status and isError.

Errors

Read error.code from the JSON body together with the HTTP status. The envelope around it varies by layer, so key off those two. error.chargeState, when present, says whether money moved: none, held, released or unknown. When it is unknown, read the run before assuming nothing was charged.

Error codes, what they mean and what an agent should do
StatusCodeMeaningWhat the agent does
400INVALID_INPUTThe request body failed validation: an unknown or missing key, accept not true, an invalid idempotency key, a runId that is not a UUID, or a tool input that does not match its contract (for example a malformed CIK). error.details.issues names the field, never its value.Fix the request. Nothing was charged. Never resend it unchanged.
400QUOTE_MISMATCHThe quote was edited, or was issued for a different key, tool, organization or input.Request a new quote with the same key and input and send it back unchanged.
401UNAUTHORIZEDThe key is missing, malformed, unknown, revoked, or for the wrong channel (REST needs API, MCP needs MCP). All causes look the same on purpose.Do not retry. Check the key and its channel, then ask the owner to create or rotate it. Never log the key.
402FUNDING_REQUIREDThe organization has no confirmed funding yet. A payment redirect alone does not credit a wallet.Stop and ask the owner to fund the wallet in the Console. Quotes and reading runs still work.
402INSUFFICIENT_BALANCEThe wallet is funded but the available balance is below the amount to reserve.Ask the owner to add funds, then retry with the same idempotency key.
402SPEND_LIMIT_EXCEEDEDThe quote's maximum is above the key's per-request limit, or would take it past its daily limit.Ask the owner to raise the limit, or wait for the next UTC day. Do not split or alter the quote.
403SCOPE_MISSINGThe key does not carry the company.read scope.Do not retry. Ask the owner for a key with company.read.
403TENANT_UNAVAILABLEThe organization is not active or verified, or cannot be served in this region.Stop. The owner must resolve the organization status in the Console.
403TOOL_UNAVAILABLEThe tool is not available to this organization. When error.details.reason is licence_acceptance_required, the organization has not accepted the Console data licence yet; error.details.nextStepUrl is the Console page where an owner or admin accepts it. Quotes work without it.For licence_acceptance_required, ask an owner or admin to accept the licence at nextStepUrl, then retry the same request. Otherwise re-read GET /tools; if availability is not AVAILABLE, stop and tell the customer it is not offered. Nothing was charged.
403ACCOUNT_SUSPENDEDThe commerce account is suspended or closed.Stop. The owner must contact Altss support.
403console_access_restrictedThe person who created the key has not accepted the current terms, or Console access is not open to them.Stop. Ask that person to sign in to the Console and accept the current terms.
404SUBJECT_NOT_FOUNDSEC has no data for that CIK. The reservation is released in full.Do not retry the same CIK. Tell the customer. The charge is $0.
404RUN_NOT_FOUNDNo run with that id exists for this organization.Check the runId from your earlier response.
409QUOTE_STALEThe quote expired (15 minutes), or the price, tool version, use terms or plan changed since it was issued.Quote again, show the price, maximum, expiry, plan and use terms to the customer, and obtain authorization again. Never auto-accept.
409REQUEST_IN_PROGRESSThe same idempotency key is still running. The charge state is unknown until it finishes.Wait a few seconds, then read the run (error.details.runId) or retry with the same key. Never create a new key.
422IDEMPOTENCY_CONFLICTThe key was already used for a different tool, version or input.Use a new unique key for a genuinely new purchase. For a retry, resend the original request unchanged.
429RATE_LIMITEDA per-key, per-tool or per-address limit was reached.Back off for a minute and retry. Retry a purchase with the same idempotency key.
502EXECUTION_FAILEDThe task failed (SEC data unavailable, the issuer is not eligible, or a required period or metric is missing). The reservation is released.If chargeState is released, retry with the same key. If unknown, read the run first.
502OUTPUT_BOUND_EXCEEDEDThe result was larger than the response limits. The reservation is released.Do not retry. Choose a different issuer. The charge is $0.
503LEDGER_UNAVAILABLEThe ledger or a spend-limit check failed temporarily. A hold, if any, returns in full.Retry with the same idempotency key, or read the run.
503OUTCOME_UNAVAILABLEAn unexpected failure meant the outcome of the purchase cannot be confirmed.Do not assume zero charge. Retry with the same idempotency key, or read the run with GET /runs/{runId}.
504EXECUTION_TIMEOUTThe tool took longer than 25 seconds. The reservation is released in full.Retry with the same idempotency key after a short delay.