# Wallbit API Development Rules
## API Context
Wallbit is a global neobank and the world's first to offer a public API for programmatic account control. We offer US accounts, investments in ETFs, stocks and bonds, and local currency rails.
The Public API enables:
- Account balance queries (checking and investments)
- Transaction history
- Trading (stocks, ETFs, bonds)
- Bank account details (ACH/SEPA)
- Crypto wallet management
Base URL: `https://api.wallbit.io`
## Authentication
All requests require `X-API-Key` header:
```javascript
const headers = { 'X-API-Key': process.env.WALLBIT_API_KEY };
```
## Endpoints Reference
### Balance
- `GET /api/public/v1/balance/checking` - USD/EUR balances
- `GET /api/public/v1/balance/stocks` - Stock portfolio
### Transactions
- `GET /api/public/v1/transactions` - History with filters
- Query params: page, limit, status, type, currency, from_date, to_date
### Trades
- `POST /api/public/v1/trades` - Buy/sell stocks
- Body: symbol, direction, currency, order_type, amount OR shares
### Account
- `GET /api/public/v1/account-details` - Bank details (ACH/SEPA)
- `GET /api/public/v1/wallets` - Crypto addresses
### Assets
- `GET /api/public/v1/assets` - List stocks/ETFs
- `GET /api/public/v1/assets/{symbol}` - Asset info
### Operations
- `POST /api/public/v1/operations/internal` - Transfer between accounts
## Code Standards
- Always use environment variables for API keys
- Implement error handling for all status codes
- Add TypeScript types for API responses
- Use async/await, not callbacks
- Implement rate limit handling (429 responses)
## Example Patterns
### Fetching data
```javascript
async function getBalance() {
const response = await fetch('https://api.wallbit.io/api/public/v1/balance/checking', {
headers: { 'X-API-Key': process.env.WALLBIT_API_KEY }
});
if (!response.ok) throw new Error(`API Error: ${response.status}`);
return response.json();
}
```
### Executing trades
```javascript
async function buyStock(symbol, amount) {
const response = await fetch('https://api.wallbit.io/api/public/v1/trades', {
method: 'POST',
headers: {
'X-API-Key': process.env.WALLBIT_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
symbol,
direction: 'BUY',
currency: 'USD',
order_type: 'MARKET',
amount
})
});
return response.json();
}
```
## Error Handling
Handle these status codes:
- `401` - Check API key is valid
- `403` - Check API key permissions
- `412` - User needs to complete KYC
- `422` - Validate request parameters
- `429` - Implement backoff and retry