{"openapi":"3.1.0","info":{"title":"CitizenX Agent Pricing API","version":"1.0.0","description":"Anonymous, read-only pricing quotes for citizenship-by-investment program routes. Prices are informational estimates and are not binding offers."},"servers":[{"url":"https://citizenx.com/api"}],"paths":{"/agent/pricing/v1/quote":{"post":{"operationId":"getProgramPrices","summary":"Get program prices for a family","description":"Returns fully eligible open program routes for the supplied family, and lists ineligible programs with exclusion reasons. Never returns partial-family prices.","tags":["Agent Pricing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPricingQuoteRequest"},"examples":{"singleMainApplicant":{"summary":"Single main applicant","value":{"applicants":[{"role":"main","age":40,"nationalityCountryCode":"US"}]}},"multiMemberFamily":{"summary":"Main applicant with spouse and child","value":{"applicants":[{"role":"main","age":42,"nationalityCountryCode":"GB"},{"role":"spouse","age":40,"nationalityCountryCode":"GB"},{"role":"child","age":12,"nationalityCountryCode":"GB"}],"routeTypes":["donation"]}}}}}},"responses":{"200":{"description":"Pricing quote","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}},"RateLimit":{"schema":{"type":"string"},"description":"Current remaining quota per IETF rate-limit header draft."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Configured quota policies per IETF rate-limit header draft."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPricingQuoteResponse"},"examples":{"mixedEligibility":{"summary":"Eligible and ineligible programs","value":{"provider":"CitizenX","calculatedAt":"2026-07-31T12:00:00.000Z","notice":"Prices are informational estimates based on current published rules and are not binding offers.","eligiblePrograms":[{"programId":"antigua-citizenship","programName":"Antigua & Barbuda Citizenship","countryCode":"AG","countryName":"Antigua and Barbuda","routes":[{"routeId":"antigua-ndf@2025","routeName":"National Development Fund","routeType":"donation","processingTime":"6-8 months","currency":"USD","costSummary":{"processingCost":50000,"platformCost":0,"investmentCost":0,"contributionCost":230000,"totalCost":280000},"totalCost":280000,"paymentStages":[{"stage":"contribution","name":"Contribution","cost":230000},{"stage":"submission","name":"Government fees","cost":50000}]}]}],"ineligiblePrograms":[{"programId":"example-ineligible","programName":"Example Program","countryCode":"XX","countryName":"Example","exclusions":[{"memberIndex":2,"role":"child","reason":"Child exceeds maximum age."}]}]}}}}}},"400":{"description":"Validation or malformed request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Request body exceeds 16 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit":{"schema":{"type":"string"}},"RateLimit-Policy":{"schema":{"type":"string"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"AgentPricingApplicantRole":{"type":"string","enum":["main","spouse","child","parent","sibling"]},"AgentPricingApplicant":{"type":"object","additionalProperties":false,"required":["role","age","nationalityCountryCode"],"properties":{"role":{"$ref":"#/components/schemas/AgentPricingApplicantRole"},"age":{"type":"integer","minimum":0,"maximum":150},"nationalityCountryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO-3166-1 alpha-2 country code","examples":["US","GB"]}}},"AgentPricingQuoteRequest":{"type":"object","additionalProperties":false,"required":["applicants"],"properties":{"applicants":{"type":"array","minItems":1,"maxItems":12,"items":{"$ref":"#/components/schemas/AgentPricingApplicant"}},"programIds":{"type":"array","items":{"type":"string"},"uniqueItems":true},"countryCodes":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"uniqueItems":true},"routeTypes":{"type":"array","items":{"type":"string","enum":["donation","real-estate","enterprise","bond"]},"uniqueItems":true}}},"CostSummary":{"type":"object","additionalProperties":false,"required":["processingCost","platformCost","investmentCost","contributionCost","totalCost"],"properties":{"processingCost":{"type":"number"},"platformCost":{"type":"number"},"investmentCost":{"type":"number"},"contributionCost":{"type":"number"},"totalCost":{"type":"number"}}},"AgentPricingPaymentStageTotal":{"type":"object","additionalProperties":false,"required":["stage","name","cost"],"properties":{"stage":{"type":"string","enum":["down_payment","submission","escrow","contribution","investment","issuance","extra"]},"name":{"type":"string"},"cost":{"type":"number"}}},"AgentPricingRouteQuote":{"type":"object","additionalProperties":false,"required":["routeId","routeName","routeType","processingTime","currency","costSummary","totalCost","paymentStages"],"properties":{"routeId":{"type":"string"},"routeName":{"type":"string"},"routeType":{"type":"string","enum":["donation","real-estate","enterprise","bond"]},"processingTime":{"type":"string"},"currency":{"type":"string","enum":["USD","EUR"]},"costSummary":{"$ref":"#/components/schemas/CostSummary"},"totalCost":{"type":"number"},"paymentStages":{"type":"array","items":{"$ref":"#/components/schemas/AgentPricingPaymentStageTotal"}}}},"AgentPricingEligibleProgram":{"type":"object","additionalProperties":false,"required":["programId","programName","countryCode","countryName","routes"],"properties":{"programId":{"type":"string"},"programName":{"type":"string"},"countryCode":{"type":"string"},"countryName":{"type":"string"},"routes":{"type":"array","items":{"$ref":"#/components/schemas/AgentPricingRouteQuote"}}}},"AgentPricingExclusion":{"type":"object","additionalProperties":false,"required":["memberIndex","role","reason"],"properties":{"memberIndex":{"type":"integer","minimum":0},"role":{"$ref":"#/components/schemas/AgentPricingApplicantRole"},"reason":{"type":"string"}}},"AgentPricingIneligibleProgram":{"type":"object","additionalProperties":false,"required":["programId","programName","countryCode","countryName","exclusions"],"properties":{"programId":{"type":"string"},"programName":{"type":"string"},"countryCode":{"type":"string"},"countryName":{"type":"string"},"exclusions":{"type":"array","items":{"$ref":"#/components/schemas/AgentPricingExclusion"}}}},"AgentPricingQuoteResponse":{"type":"object","additionalProperties":false,"required":["provider","calculatedAt","notice","eligiblePrograms","ineligiblePrograms"],"properties":{"provider":{"type":"string","const":"CitizenX"},"calculatedAt":{"type":"string","format":"date-time"},"notice":{"type":"string","const":"Prices are informational estimates based on current published rules and are not binding offers."},"eligiblePrograms":{"type":"array","items":{"$ref":"#/components/schemas/AgentPricingEligibleProgram"}},"ineligiblePrograms":{"type":"array","items":{"$ref":"#/components/schemas/AgentPricingIneligibleProgram"}}}},"ProblemDetails":{"type":"object","additionalProperties":true,"required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}}}}}}