{ "openapi": "3.1.0", "info": { "title": "Crebit Lock API, Partner integration", "version": "0.1.0", "description": "Partner-facing HTTP API for FX rate locks: quotes, contracts, inbound webhooks (partner → Crebit), and outbound payout webhooks (Crebit → partner). Crebit operates custody, pricing engines, and settlement internally, partners integrate only with these routes." }, "servers": [ { "url": "https://lock-apis-test.crebitpay.com", "description": "Sandbox" }, { "url": "https://lock-apis.crebitpay.com", "description": "Production" } ], "tags": [ { "name": "Partner", "description": "Account verification" }, { "name": "Quotes", "description": "Rate lock quotes" }, { "name": "Contracts", "description": "Lock terms from accepted quotes" }, { "name": "Webhooks", "description": "Inbound (partner → Crebit) lifecycle events" }, { "name": "Outbound webhooks", "description": "Crebit → partner. Posted to your configured webhook_url after a payout settles or fails." } ], "paths": { "/api/v1/partners/me": { "get": { "tags": [ "partner-api-keys" ], "summary": "Partner Me", "operationId": "partner_me_api_v1_partners_me_get", "parameters": [ { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerMeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/fx/webhooks/inbound": { "post": { "tags": [ "Webhooks" ], "summary": "Notify Crebit of an inbound event", "operationId": "post_inbound_webhook_api_v1_fx_webhooks_inbound_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InboundFundsInRouteEvent" }, { "$ref": "#/components/schemas/InboundContractExercisedEvent" } ], "discriminator": { "propertyName": "event_type", "mapping": { "funds_in_route": "#/components/schemas/InboundFundsInRouteEvent", "contract_exercised": "#/components/schemas/InboundContractExercisedEvent" } }, "title": "Body" }, "examples": { "funds_in_route, deposit dispatched": { "summary": "Partner sent the deposit leg on-chain", "value": { "event_type": "funds_in_route", "fx_contract_id": "33333333-3333-4333-8333-333333333333", "payment_type": "deposit", "amount": "5000.00", "currency": "USDC", "chain": "ethereum", "transaction_hash": "0xabc123...", "source_wallet_address": "0xPartnerTreasury..." } }, "contract_exercised, customer transacted": { "summary": "Customer transacted within the lock window; pay them the FX delta", "value": { "event_type": "contract_exercised", "fx_contract_id": "33333333-3333-4333-8333-333333333333", "executed_at": "2026-08-07T13:42:00Z", "live_execution_rate": "5.51", "payout_wallet_address": "0xEndUserWallet..." } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation / business rule" }, "409": { "description": "Idempotency conflict" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Partner → Crebit. Two event_types are supported:\n\n* `funds_in_route`, partner has dispatched premium or deposit on-chain and the contract should advance to active.\n* `contract_exercised`, the customer transacted within the lock window. Crebit compares live_execution_rate against the contract's locked_rate, computes any FX delta owed, and pays it out to payout_wallet_address in the contract's settlement_currency on the contract's chain. Crebit then delivers an outbound payout_settled (or payout_failed) webhook to your configured webhook_url." } }, "/api/v1/fx/webhook-events": { "get": { "tags": [ "Dashboard" ], "summary": "List Webhook Events", "operationId": "list_webhook_events_api_v1_fx_webhook_events_get", "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "incoming", "outgoing" ], "type": "string" }, { "type": "null" } ], "title": "Direction" } }, { "name": "fx_contract_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Fx Contract Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque keyset cursor", "title": "Cursor" }, "description": "Opaque keyset cursor" }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/fx/quotes": { "post": { "tags": [ "Quotes" ], "summary": "Request a rate-lock quote", "description": "Price a rate lock for a customer. The lock window is a calendar range — the customer may execute the locked rate at ANY moment from window_start through window_end (inclusive). The chain + settlement_currency fix the settlement rail at quote time.", "operationId": "post_create_quote_api_v1_fx_quotes_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteCreateRequest" }, "examples": { "USD → BRL forward, USDC on Ethereum": { "summary": "One-week forward. Settlement (fee + payout) in USDC on Ethereum. Includes a 30bp partner spread.", "value": { "customer_reference_id": "partner-cust-ref-2026-0042", "customer_name": "Acme Imports Pvt Ltd", "contract_type": "forward", "direction": "USD_TO_BRL", "notional_currency": "USD", "notional_amount": "50000.00", "provider_rate": "5.42", "market_rate": "5.4227", "market_rate_timestamp": "2026-05-24T16:00:00Z", "provider_extra_spread": "0.0030", "window_start": "2026-08-04T00:00:00Z", "window_end": "2026-08-11T00:00:00Z", "chain": "ethereum", "settlement_currency": "USDC" } }, "USD → MXN option, USDT on Polygon": { "summary": "Two-week option. Settlement in USDT on Polygon.", "value": { "customer_reference_id": "partner-cust-ref-2026-0099", "customer_name": "Sample Co.", "contract_type": "option", "direction": "USD_TO_MXN", "notional_currency": "USD", "notional_amount": "25000.00", "provider_rate": "17.21", "market_rate": "17.2186", "market_rate_timestamp": "2026-05-24T16:00:00Z", "window_start": "2026-09-01T00:00:00Z", "window_end": "2026-09-14T23:59:59Z", "chain": "polygon", "settlement_currency": "USDT" } }, "BRL → USD forward, USDC on Ethereum": { "summary": "Reverse corridor, Brazilian importer protecting USD-receivable.", "value": { "customer_reference_id": "partner-cust-ref-2026-0080", "customer_name": "Sao Paulo Tech LTDA", "contract_type": "forward", "direction": "BRL_TO_USD", "notional_currency": "BRL", "notional_amount": "300000.00", "provider_rate": "0.1847", "market_rate": "0.1848", "market_rate_timestamp": "2026-05-24T16:00:00Z", "window_start": "2026-08-10T09:00:00Z", "window_end": "2026-09-10T17:00:00Z", "chain": "ethereum", "settlement_currency": "USDC" } }, "EUR → USD next-day window, EURC on Solana": { "summary": "Short window, 24h apart. Settlement in EURC on Solana.", "value": { "customer_reference_id": "partner-cust-ref-2026-0100", "customer_name": "Atlas Trading SA", "contract_type": "forward", "direction": "EUR_TO_USD", "notional_currency": "EUR", "notional_amount": "100000.00", "provider_rate": "1.0825", "market_rate": "1.0830", "market_rate_timestamp": "2026-05-24T16:00:00Z", "window_start": "2026-08-04T12:00:00Z", "window_end": "2026-08-05T12:00:00Z", "chain": "solana", "settlement_currency": "EURC" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Quotes" ], "summary": "List quotes", "operationId": "get_list_quotes_api_v1_fx_quotes_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "created", "failed" ], "type": "string" }, { "type": "null" } ], "description": "Filter by API status: created (includes accepted quotes) or failed (includes expired).", "title": "Status" }, "description": "Filter by API status: created (includes accepted quotes) or failed (includes expired)." }, { "name": "customer_reference_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Reference Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor", "title": "Cursor" }, "description": "Opaque pagination cursor" }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedQuotes" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/fx/quotes/{quote_id}": { "get": { "tags": [ "Quotes" ], "summary": "Get quote", "operationId": "get_quote_api_v1_fx_quotes__quote_id__get", "parameters": [ { "name": "quote_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Quote Id" } }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/fx/contracts": { "post": { "tags": [ "Contracts" ], "summary": "Lock the quote (create the contract)", "description": "Convert an accepted quote into a binding rate lock. Pass the quote_id returned by POST /api/v1/fx/quotes plus your own partner_transaction_reference. The contract inherits the quote's lock window, chain, and settlement_currency; those terms are immutable once the contract exists.", "operationId": "post_create_contract_api_v1_fx_contracts_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractCreateRequest" }, "examples": { "Lock an accepted quote": { "value": { "quote_id": "22222222-2222-4222-8222-222222222222", "partner_transaction_reference": "platform-tx-9901" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FxContractResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/fx/customers/{customer_reference_id}/locks": { "get": { "tags": [ "Contracts" ], "summary": "List FX locks for a customer", "description": "Returns paginated FX contracts (locks) for the partner's opaque customer_reference_id, newest first.", "operationId": "get_customer_locks_api_v1_fx_customers__customer_reference_id__locks_get", "parameters": [ { "name": "customer_reference_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Reference Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "quote_created", "funds_in_route", "active", "exercised", "settled", "expired", "failed", "defaulted", "deposit_forfeited" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor", "title": "Cursor" }, "description": "Opaque pagination cursor" }, { "name": "X-Crebit-Key-Id", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Id" } }, { "name": "X-Crebit-Key-Secret", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Key-Secret" } }, { "name": "X-Crebit-Environment", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Crebit-Environment" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLocks" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "PaginatedLocks": { "properties": { "items": { "items": { "$ref": "#/components/schemas/FxLockResponse" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "PaginatedLocks" }, "FxLockResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "crebit_contract_reference": { "type": "string", "title": "Crebit Contract Reference" }, "locked_rate": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Locked Rate" }, "provider_rate_at_lock": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Provider Rate At Lock" }, "market_rate_at_lock": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Market Rate At Lock" }, "premium_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Premium Amount" }, "deposit_amount": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Deposit Amount" }, "total_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Total Amount" }, "window_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Window Start" }, "window_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Window End" }, "chain": { "type": "string", "enum": [ "solana", "ethereum", "polygon" ], "title": "Chain" }, "settlement_currency": { "type": "string", "enum": [ "USDC", "USDT", "EURC" ], "title": "Settlement Currency" }, "funding_wallet_address": { "type": "string", "title": "Funding Wallet Address", "description": "Blockchain address to fund premium and deposit. Uses FX_FUNDING_WALLET_ADDRESS until a wallet service is integrated." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "max_transaction_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Max Transaction Amount" }, "status": { "type": "string", "enum": [ "quote_created", "funds_in_route", "active", "exercised", "settled", "expired", "failed", "defaulted", "deposit_forfeited" ], "title": "Status" }, "quote_id": { "type": "string", "format": "uuid", "title": "Quote Id" }, "customer_reference_id": { "type": "string", "title": "Customer Reference Id", "description": "Partner-supplied opaque customer id (not Crebit internal UUID)." }, "partner_transaction_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner Transaction Reference" } }, "type": "object", "required": [ "id", "crebit_contract_reference", "locked_rate", "provider_rate_at_lock", "market_rate_at_lock", "premium_amount", "total_amount", "chain", "settlement_currency", "funding_wallet_address", "created_at", "max_transaction_amount", "status", "quote_id", "customer_reference_id" ], "title": "FxLockResponse", "description": "Partner-facing FX lock (contract) row for customer-scoped listings." }, "FxContractResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "crebit_contract_reference": { "type": "string", "title": "Crebit Contract Reference" }, "locked_rate": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Locked Rate" }, "provider_rate_at_lock": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Provider Rate At Lock" }, "market_rate_at_lock": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Market Rate At Lock" }, "premium_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Premium Amount" }, "deposit_amount": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Deposit Amount" }, "total_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Total Amount" }, "window_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Window Start" }, "window_end": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Window End" }, "chain": { "type": "string", "enum": [ "solana", "ethereum", "polygon" ], "title": "Chain" }, "settlement_currency": { "type": "string", "enum": [ "USDC", "USDT", "EURC" ], "title": "Settlement Currency" }, "funding_wallet_address": { "type": "string", "title": "Funding Wallet Address", "description": "Blockchain address to fund premium and deposit. Uses FX_FUNDING_WALLET_ADDRESS until a wallet service is integrated." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "max_transaction_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Max Transaction Amount" } }, "type": "object", "required": [ "id", "crebit_contract_reference", "locked_rate", "provider_rate_at_lock", "market_rate_at_lock", "premium_amount", "total_amount", "chain", "settlement_currency", "funding_wallet_address", "created_at", "max_transaction_amount" ], "title": "FxContractResponse", "description": "Public contract body (spec: slim amounts, window, chain, funding address)." }, "ContractCreateRequest": { "properties": { "quote_id": { "type": "string", "format": "uuid", "title": "Quote Id" }, "partner_transaction_reference": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Partner Transaction Reference" } }, "additionalProperties": false, "type": "object", "required": [ "quote_id" ], "title": "ContractCreateRequest" }, "PaginatedQuotes": { "properties": { "items": { "items": { "$ref": "#/components/schemas/QuoteResponse" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "items" ], "title": "PaginatedQuotes" }, "QuoteResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "type": "string", "enum": [ "created", "failed" ], "title": "Status" }, "locked_rate": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Locked Rate" }, "strike_mode": { "type": "string", "enum": [ "cip_fair", "live_spot", "custom" ], "title": "Strike Mode", "default": "cip_fair" }, "target_strike": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Target Strike" }, "strike_advantage_bps": { "type": "integer", "minimum": 0, "title": "Strike Advantage Bps", "description": "Basis points of rate advantage vs market; 0 when not yet computable." }, "provider_extra_spread": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Provider Extra Spread", "description": "Optional partner extra spread from the quote request (echo)." }, "premium_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Premium Amount" }, "deposit_amount": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Deposit Amount" }, "total_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Total Amount" }, "window_start": { "type": "string", "format": "date-time", "title": "Window Start" }, "window_end": { "type": "string", "format": "date-time", "title": "Window End" }, "chain": { "type": "string", "enum": [ "solana", "ethereum", "polygon" ], "title": "Chain" }, "settlement_currency": { "type": "string", "enum": [ "USDC", "USDT", "EURC" ], "title": "Settlement Currency" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "status", "locked_rate", "strike_advantage_bps", "premium_amount", "total_amount", "window_start", "window_end", "chain", "settlement_currency", "expires_at", "created_at" ], "title": "QuoteResponse", "description": "Partner-facing quote resource (slimmed per spec; DB may hold extra lifecycle fields)." }, "QuoteCreateRequest": { "properties": { "customer_reference_id": { "type": "string", "maxLength": 256, "minLength": 1, "title": "Customer Reference Id" }, "customer_name": { "type": "string", "maxLength": 256, "minLength": 1, "title": "Customer Name", "description": "Human-readable name of the partner's customer or business (used for audit, support, and contract documents)." }, "contract_type": { "type": "string", "enum": [ "option", "forward" ], "title": "Contract Type" }, "direction": { "type": "string", "enum": [ "BRL_TO_USD", "USD_TO_BRL", "BRL_TO_EUR", "BRL_TO_MXN", "USD_TO_EUR", "EUR_TO_USD", "NGN_TO_USD" ], "title": "Direction" }, "notional_currency": { "type": "string", "enum": [ "USD", "BRL", "MXN", "EUR" ], "title": "Notional Currency" }, "notional_amount": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Notional Amount" }, "provider_rate": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Provider Rate", "description": "Partner live FX rate at quote time (provider_rate in pricing breakdown)." }, "market_rate": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Market Rate", "description": "Benchmark market rate at quote time." }, "market_rate_timestamp": { "type": "string", "format": "date-time", "title": "Market Rate Timestamp", "description": "ISO-8601 UTC time when market_rate was observed. Must be within PRICING_MARKET_RATE_MAX_AGE_SECONDS (default 300s)." }, "provider_extra_spread": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Provider Extra Spread", "description": "Optional extra provider spread (decimal string) applied on top of base pricing." }, "strike_mode": { "type": "string", "enum": [ "cip_fair", "live_spot", "custom" ], "title": "Strike Mode", "description": "Strike selection mode: cip_fair (default), live_spot, or custom.", "default": "cip_fair" }, "target_strike": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Target Strike", "description": "Required when strike_mode is custom." }, "window_start": { "type": "string", "format": "date-time", "title": "Window Start", "description": "Lock window start (ISO-8601 UTC). Customer may execute on or after this instant." }, "window_end": { "type": "string", "format": "date-time", "title": "Window End", "description": "Lock window end (ISO-8601 UTC). Must be after window_start." }, "chain": { "type": "string", "enum": [ "solana", "ethereum", "polygon" ], "title": "Chain" }, "settlement_currency": { "type": "string", "enum": [ "USDC", "USDT", "EURC" ], "title": "Settlement Currency" } }, "additionalProperties": false, "type": "object", "required": [ "customer_reference_id", "customer_name", "contract_type", "direction", "notional_currency", "notional_amount", "provider_rate", "market_rate", "market_rate_timestamp", "window_start", "window_end", "chain", "settlement_currency" ], "title": "QuoteCreateRequest", "description": "Create a rate-lock quote. Send the customer (customer_reference_id, customer_name), the FX corridor (direction, notional_currency, notional_amount, provider_rate), a required benchmark (market_rate + market_rate_timestamp), the lock window (window_start, window_end, ISO-8601 UTC datetimes), and the settlement rail (chain, settlement_currency)." }, "InboundContractExercisedEvent": { "properties": { "event_type": { "type": "string", "const": "contract_exercised", "title": "Event Type" }, "fx_contract_id": { "type": "string", "format": "uuid", "title": "Fx Contract Id" }, "executed_at": { "type": "string", "format": "date-time", "title": "Executed At" }, "live_execution_rate": { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$", "title": "Live Execution Rate" }, "payout_wallet_address": { "type": "string", "title": "Payout Wallet Address" }, "payout_currency": { "type": "string", "enum": [ "USDC", "BRLA" ], "title": "Payout Currency", "default": "USDC" }, "chain": { "type": "string", "enum": [ "solana", "ethereum", "polygon" ], "title": "Chain" } }, "additionalProperties": false, "type": "object", "required": [ "event_type", "fx_contract_id", "executed_at", "live_execution_rate", "payout_wallet_address", "chain" ], "title": "InboundContractExercisedEvent" }, "InboundFundsInRouteEvent": { "properties": { "event_type": { "type": "string", "const": "funds_in_route", "title": "Event Type" }, "fx_contract_id": { "type": "string", "format": "uuid", "title": "Fx Contract Id" }, "payment_type": { "anyOf": [ { "type": "string", "enum": [ "premium", "deposit" ] }, { "type": "null" } ], "title": "Payment Type", "description": "Premium or deposit leg; omit if notifying legs separately." }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?[0-9]+([.][0-9]+)?$" }, { "type": "null" } ], "title": "Amount" }, "currency": { "anyOf": [ { "type": "string", "enum": [ "USDC", "USDT", "EURC", "BRLA" ] }, { "type": "null" } ], "title": "Currency" }, "chain": { "anyOf": [ { "type": "string", "enum": [ "solana", "ethereum", "polygon" ] }, { "type": "null" } ], "title": "Chain" }, "transaction_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction Hash" }, "source_wallet_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Wallet Address" } }, "additionalProperties": false, "type": "object", "required": [ "event_type", "fx_contract_id" ], "title": "InboundFundsInRouteEvent" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "PartnerMeResponse": { "properties": { "partner_id": { "type": "string", "format": "uuid", "title": "Partner Id" }, "partner_name": { "type": "string", "title": "Partner Name" }, "api_key_id": { "type": "string", "format": "uuid", "title": "Api Key Id" }, "environment": { "type": "string", "title": "Environment" } }, "type": "object", "required": [ "partner_id", "partner_name", "api_key_id", "environment" ], "title": "PartnerMeResponse" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }