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 setupHow to use Console
1. Fund your wallet
After signup, add at least $1,000 to your wallet through Stripe Checkout.
Add funds2. 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 agent3. 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.jsonRequest 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.jsonPurchase 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 keysDeliver 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 referenceReference
- OpenAPI descriptionREST paths, request and response schemas and error responses (OpenAPI 3.1).
- Agent reference (llms.txt)The one-page guide a customer agent can read before connecting.
- Tool catalog (tools.json)The tool, its input schema and its price, as machine-readable metadata.
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.
| Status | Code | Meaning | What the agent does |
|---|---|---|---|
| 400 | INVALID_INPUT | The 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. |
| 400 | QUOTE_MISMATCH | The 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. |
| 401 | UNAUTHORIZED | The 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. |
| 402 | FUNDING_REQUIRED | The 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. |
| 402 | INSUFFICIENT_BALANCE | The 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. |
| 402 | SPEND_LIMIT_EXCEEDED | The 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. |
| 403 | SCOPE_MISSING | The key does not carry the company.read scope. | Do not retry. Ask the owner for a key with company.read. |
| 403 | TENANT_UNAVAILABLE | The organization is not active or verified, or cannot be served in this region. | Stop. The owner must resolve the organization status in the Console. |
| 403 | TOOL_UNAVAILABLE | The 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. |
| 403 | ACCOUNT_SUSPENDED | The commerce account is suspended or closed. | Stop. The owner must contact Altss support. |
| 403 | console_access_restricted | The 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. |
| 404 | SUBJECT_NOT_FOUND | SEC 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. |
| 404 | RUN_NOT_FOUND | No run with that id exists for this organization. | Check the runId from your earlier response. |
| 409 | QUOTE_STALE | The 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. |
| 409 | REQUEST_IN_PROGRESS | The 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. |
| 422 | IDEMPOTENCY_CONFLICT | The 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. |
| 429 | RATE_LIMITED | A 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. |
| 502 | EXECUTION_FAILED | The 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. |
| 502 | OUTPUT_BOUND_EXCEEDED | The result was larger than the response limits. The reservation is released. | Do not retry. Choose a different issuer. The charge is $0. |
| 503 | LEDGER_UNAVAILABLE | The 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. |
| 503 | OUTCOME_UNAVAILABLE | An 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}. |
| 504 | EXECUTION_TIMEOUT | The tool took longer than 25 seconds. The reservation is released in full. | Retry with the same idempotency key after a short delay. |