Frequently asked questions

Common questions about the Vaulto API.

Getting started

How do I get an API key?

1. Go to the Vaulto Dashboard
2. Sign in or create an account
3. Navigate to API Keys and click Create Key
4. Copy and store your key securely

See the Getting started guide for more details.

How much does the API cost?

API requests are billed per request:

• Standard endpoints: $0.002 per request (or your configured rate)
• Private company endpoints: 10x the standard rate ($0.02 per request)

Check current pricing at GET /api/pricing (no auth required) or GET /api/billing with your API key. Every response includes an X-Request-Cost-USD header showing the exact cost.

Do I need trading experience to use the API?

No prior trading experience is required. The API handles the complexity of prediction markets and weighted positions for you. However, you should understand:

• LONG = betting valuation will be higher than expected
• SHORT = betting valuation will be lower than expected
• Floor payoff = your guaranteed minimum return (higher = safer but more expensive)

See the Trading quickstart glossary for full explanations.

How do I fund my account?

1. Log in to the Dashboard
2. Navigate to Billing or Account
3. Use the Fund with USDC option to add funds

Your account balance must be positive to make API requests. If your balance is zero, the API returns 402 Payment Required.

---

Endpoints and data

What companies can I trade?

Currently, 17 pre-IPO events are supported:

• SpaceX (Higher & Lower strikes)
• OpenAI
• Anthropic
• Discord
• Stripe
• Databricks
• Fannie Mae
• Freddie Mac
• Kraken
• Perplexity
• And more...

Get the full list with GET /api/trading/events (no auth required).

What private company data is available?

The Private Companies API provides data on 150+ companies including:

• Valuation history
• Total funding and funding rounds
• Employee count
• Industry and headquarters
• Key investors and board members

See Private companies API for full details.

Why are private company endpoints billed at 10x?

Private company data is proprietary and requires ongoing research, verification, and maintenance. The 10x multiplier reflects the value of this curated dataset. Each response includes the exact cost in the X-Request-Cost-USD header.

What's the difference between public and protected endpoints?

Public endpoints (no API key required):

• GET /api/pricing — Check API pricing
• GET /api/trading/events — List available IPO events
• GET /api/trading/valuation — Get current event pricing

Protected endpoints (API key required):

• All trading operations (/api/trading/buy, /api/trading/sell, etc.)
• Position and order management
• Private company data
• Usage and billing information

---

Trading

Do I need Polymarket credentials to trade?

Yes. Vaulto executes trades through Polymarket's prediction markets. You need to:

1. Create an account at Polymarket
2. Generate API credentials (key, secret, passphrase)
3. Store them via POST /api/trading/credentials

Your credentials are encrypted with AES-256-GCM before storage.

What are floor payoffs?

Floor payoffs guarantee a minimum return even in worst-case scenarios:

Floor	Meaning	Trade-off
0.3	Keep at least 30% if all bands lose	Higher cost, more protection
0.2	Keep at least 20% in worst case	Balanced
0.1	Keep at least 10% in worst case	Lower cost, less protection

Set your floors via PUT /api/trading/settings with floorL (LONG) and floorS (SHORT) parameters.

Can I partially close a position?

Yes. When selling, set the percentage parameter (1-100):

{
  "positionId": "pos_abc123",
  "percentage": 50
}

This closes 50% of your position and keeps the rest open.

Are positions verifiable on-chain?

Yes. Positions are backed by ERC-1155 tokens on Polygon. Use POST /api/trading/positions/sync to synchronize your positions with on-chain data.

---

Technical

How do I handle rate limits?

The API enforces rate limits to ensure fair usage. If you exceed the limit:

1. You'll receive a 429 Too Many Requests response
2. The Retry-After header indicates when to retry
3. Back off exponentially and retry

See Rate limits for current limits and best practices.

What should I do if I get a 402 error?

A 402 Payment Required error means your account balance is zero or insufficient. To fix:

1. Log in to the Dashboard
2. Add funds using the Fund with USDC option
3. Retry your request

How do I track my API usage?

Use GET /api/usage to retrieve your usage records:

curl -H "x-api-key: YOUR_KEY" \
  "https://api.vaulto.ai/api/usage?limit=100"

Each record includes costUsd and currency fields showing the billed amount.

What headers should I include in requests?

Header	When to use	Example
x-api-key	All protected endpoints	vaulto_abc123...
x-user-id	Trading endpoints	0x1234...5678 (wallet address)
Content-Type	POST/PUT with JSON body	application/json
x-request-id	Optional, for debugging	my-unique-id

Is there an SDK?

Currently, we provide REST API access only. The examples in our documentation show how to use the API with:

• cURL
• JavaScript (fetch)
• Python (requests)

An official SDK may be released in the future.

---

Support

Where can I get help?

• Documentation: You're reading it! Check the guides and API reference
• Dashboard: Support options available in the Vaulto Dashboard
• API Playground: Test endpoints interactively at Playground

How do I report a bug or request a feature?

Contact support through the Dashboard or include the X-Request-Id from your API response when reporting issues. This helps us investigate problems faster.

What's the API uptime?

The API is hosted on cloud infrastructure with high availability. Check the Dashboard for current status and any scheduled maintenance.