{"openapi":"3.1.0","info":{"title":"Mayospell Trading API","version":"1.0.0","description":"Mayospell-owned, account-isolated options trading API for algorithmic clients. Sandbox limit execution is the initial environment. All order writes require an idempotency key.","contact":{"name":"Mayospell Developer Support","url":"https://www.mayospell.com/contact"}},"servers":[{"url":"https://www.mayospell.com/api/v1","description":"Mayospell API edge"}],"tags":[{"name":"System"},{"name":"Account"},{"name":"Orders"},{"name":"Positions"},{"name":"Market data"},{"name":"Events"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Read API readiness","responses":{"200":{"description":"Ready"},"503":{"description":"Not ready"}}}},"/account":{"get":{"tags":["Account"],"summary":"Read the API key owner's account","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"account:read","responses":{"200":{"description":"Account snapshot"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/orders":{"get":{"tags":["Orders"],"summary":"List orders","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"orders:read","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["all","new","filled","cancelled","rejected","expired"],"default":"all"}}],"responses":{"200":{"description":"Orders"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}},"post":{"tags":["Orders"],"summary":"Place an idempotent limit order","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"orders:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Must match clientOrderId."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceOrder"}}}},"responses":{"201":{"description":"Order accepted"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"409":{"description":"Idempotency key reused with a different payload"},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/orders/{orderId}":{"get":{"tags":["Orders"],"summary":"Read one order for timeout reconciliation","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"orders:read","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}},"delete":{"tags":["Orders"],"summary":"Cancel a working order","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"orders:write","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order cancelled; repeated cancellation is safe"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"409":{"description":"Order is no longer working"},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/positions":{"get":{"tags":["Positions"],"summary":"List open positions","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"positions:read","responses":{"200":{"description":"Positions"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/positions/{symbol}/close":{"post":{"tags":["Positions"],"summary":"Submit a sell-to-close limit order","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"orders:write","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosePosition"}}}},"responses":{"201":{"description":"Close order accepted"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/fills":{"get":{"tags":["Orders"],"summary":"List fills","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"orders:read","responses":{"200":{"description":"Fills"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/contracts":{"get":{"tags":["Market data"],"summary":"Discover active option contracts","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"marketdata:read","parameters":[{"name":"underlying","in":"query","required":true,"schema":{"type":"string","example":"SPY"}}],"responses":{"200":{"description":"Contracts"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/quotes":{"get":{"tags":["Market data"],"summary":"Read option quote snapshots","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"marketdata:read","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated OCC symbols, up to 100."}],"responses":{"200":{"description":"Quotes"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/bars":{"get":{"tags":["Market data"],"summary":"Read historical option bars","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"marketdata:read","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"}},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"timeframe","in":"query","schema":{"type":"string","enum":["1Min","5Min","15Min","1Hour","1Day"]}}],"responses":{"200":{"description":"Bars"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/market-stream":{"get":{"tags":["Market data"],"summary":"Stream authenticated option quotes over SSE","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"marketdata:read","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated OCC symbols, up to 100."}],"responses":{"200":{"description":"Quote and snapshot events","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}},"/events":{"get":{"tags":["Events"],"summary":"Stream resumable account events over SSE","description":"Reconnect with Last-Event-ID to resume after the last processed event.","security":[{"MayospellApiKey":[]}],"x-mayospell-scope":"events:read","parameters":[{"name":"Last-Event-ID","in":"header","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"text/event-stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"403":{"description":"Scope, ownership, environment, or risk policy denied the request","content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}},"429":{"description":"Distributed per-key rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string"}}}}}}}}}},"components":{"securitySchemes":{"MayospellApiKey":{"type":"http","scheme":"bearer","bearerFormat":"mayo_sk_sandbox_...","description":"Create in the Mayospell API desk. The secret is displayed once."}},"schemas":{"PlaceOrder":{"type":"object","additionalProperties":false,"required":["clientOrderId","symbol","side","quantity","type","limitPrice"],"properties":{"clientOrderId":{"type":"string","format":"uuid"},"symbol":{"type":"string","description":"Exact OCC symbol"},"side":{"type":"string","enum":["buy","sell"]},"quantity":{"type":"integer","minimum":1},"type":{"type":"string","const":"limit"},"limitPrice":{"type":"number","exclusiveMinimum":0},"timeInForce":{"type":"string","enum":["day","gtc"],"default":"day"}}},"ClosePosition":{"type":"object","additionalProperties":false,"required":["clientOrderId","quantity","limitPrice"],"properties":{"clientOrderId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"limitPrice":{"type":"number","exclusiveMinimum":0},"timeInForce":{"type":"string","enum":["day","gtc"],"default":"day"}}}}}}