{"openapi":"3.1.0","info":{"title":"Vault API","version":"1.0.0","description":"Multi-currency wallets on a double-entry ledger. Amounts are integers in minor units (cents) in responses; requests accept decimal strings."},"servers":[{"url":"https://vault.fabiancollado.net"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"vlt_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["insufficient_funds"]},"message":{"type":"string"},"errors":{"type":"object"}}}}},"Account":{"type":"object","properties":{"id":{"type":"integer"},"currency":{"type":"string","enum":["USD","EUR","GBP"]},"name":{"type":"string"},"number":{"type":"string"},"balance":{"type":"integer"},"balance_usd":{"type":"integer"}}},"Transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"created_at":{"type":"string"}}}}},"paths":{"/api/v1/auth/register":{"post":{"tags":["Auth"],"summary":"Create a customer and get a token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Ada Lovelace","email":"ada@example.com","password":"correct horse battery"}}}},"responses":{"201":{"description":"Created"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/auth/token":{"post":{"tags":["Auth"],"summary":"Exchange credentials (and OTP when 2FA is on) for a Bearer token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"email":"alex@vault.demo","password":"vault-demo-2026","otp":"123456"}}}},"responses":{"201":{"description":"Token issued"},"401":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Auth"],"summary":"Revoke the current token","security":[{"bearer":[]}],"responses":{"204":{"description":"Revoked"}}}},"/api/v1/me":{"get":{"tags":["Account"],"summary":"Current customer","security":[{"bearer":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/accounts":{"get":{"tags":["Account"],"summary":"Wallets and balances","security":[{"bearer":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/transactions":{"get":{"tags":["Account"],"summary":"Ledger lines for the customer","security":[{"bearer":[]}],"parameters":[{"name":"currency","in":"query","required":false,"schema":{"type":"string"},"description":"USD | EUR | GBP"},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"groceries, dining, …"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search description"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page (1-based)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1-100"}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/insights":{"get":{"tags":["Account"],"summary":"Spending by category and balance history","security":[{"bearer":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer"},"description":"7 | 30 | 90"}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/rates":{"get":{"tags":["FX"],"summary":"Mid-market rates and fee","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/quotes":{"get":{"tags":["FX"],"summary":"Quote an exchange","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"USD"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"EUR"},{"name":"amount","in":"query","required":false,"schema":{"type":"string"},"description":"100.00"}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/transfers":{"post":{"tags":["Money movement"],"summary":"Send money to another customer","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Unique key per logical operation. Replays return the original response with `Idempotent-Replayed: true`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"to_email":"sam@vault.demo","currency":"USD","amount":"25.00","note":"Lunch 🍕"}}}},"responses":{"201":{"description":"Completed"},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/exchanges":{"post":{"tags":["Money movement"],"summary":"Convert between your own wallets","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Unique key per logical operation. Replays return the original response with `Idempotent-Replayed: true`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"from_currency":"USD","to_currency":"EUR","amount":"100.00"}}}},"responses":{"201":{"description":"Completed"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/2fa/setup":{"post":{"tags":["Security"],"summary":"Generate a TOTP secret","security":[{"bearer":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/2fa/enable":{"post":{"tags":["Security"],"summary":"Confirm a code, enable 2FA and receive recovery codes","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"code":"123456"}}}},"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/2fa/disable":{"post":{"tags":["Security"],"summary":"Disable 2FA with a TOTP or recovery code","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"code":"123456"}}}},"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/tokens":{"get":{"tags":["Security"],"summary":"List personal API tokens","security":[{"bearer":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"post":{"tags":["Security"],"summary":"Create a personal API token","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"CI"}}}},"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/tokens/{id}":{"delete":{"tags":["Security"],"summary":"Revoke a token","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/audit":{"get":{"tags":["Security"],"summary":"Audit trail (last 50 events)","security":[{"bearer":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/api/v1/ledger/verify":{"get":{"tags":["Ledger"],"summary":"Prove every journal entry nets to zero","responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}}}}