# Models

## The APIResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}}}
```

## The CryptoCurrencyCapability object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CryptoCurrencyCapability":{"type":"object","properties":{"code":{"type":"string","description":"Cryptocurrency code (e.g., BTC, ETH)"},"name":{"type":"string","description":"Cryptocurrency name"},"contract":{"type":"string","description":"Token contract address (for ERC-20 tokens)"},"decimals":{"type":"integer","format":"int64","description":"Token decimals (number of decimal places)"},"blockchains":{"type":"array","items":{"type":"string"},"description":"List of supported blockchain names/slugs"}}}}}}
```

## The CryptoCurrenciesResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CryptoCurrenciesResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CryptoCurrencyCapability"}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CryptoCurrencyCapability":{"type":"object","properties":{"code":{"type":"string","description":"Cryptocurrency code (e.g., BTC, ETH)"},"name":{"type":"string","description":"Cryptocurrency name"},"contract":{"type":"string","description":"Token contract address (for ERC-20 tokens)"},"decimals":{"type":"integer","format":"int64","description":"Token decimals (number of decimal places)"},"blockchains":{"type":"array","items":{"type":"string"},"description":"List of supported blockchain names/slugs"}}}}}}
```

## The BlockchainCapability object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"BlockchainCapability":{"type":"object","properties":{"name":{"type":"string","description":"Blockchain name"},"slug":{"type":"string","description":"Blockchain slug identifier"},"ticker":{"type":"string","description":"Blockchain ticker symbol"},"crypto_currencies":{"type":"array","items":{"$ref":"#/components/schemas/CryptoCurrencyCapability"},"description":"List of cryptocurrencies supported on this blockchain"}}},"CryptoCurrencyCapability":{"type":"object","properties":{"code":{"type":"string","description":"Cryptocurrency code (e.g., BTC, ETH)"},"name":{"type":"string","description":"Cryptocurrency name"},"contract":{"type":"string","description":"Token contract address (for ERC-20 tokens)"},"decimals":{"type":"integer","format":"int64","description":"Token decimals (number of decimal places)"},"blockchains":{"type":"array","items":{"type":"string"},"description":"List of supported blockchain names/slugs"}}}}}}
```

## The BlockchainsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"BlockchainsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlockchainCapability"}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"BlockchainCapability":{"type":"object","properties":{"name":{"type":"string","description":"Blockchain name"},"slug":{"type":"string","description":"Blockchain slug identifier"},"ticker":{"type":"string","description":"Blockchain ticker symbol"},"crypto_currencies":{"type":"array","items":{"$ref":"#/components/schemas/CryptoCurrencyCapability"},"description":"List of cryptocurrencies supported on this blockchain"}}},"CryptoCurrencyCapability":{"type":"object","properties":{"code":{"type":"string","description":"Cryptocurrency code (e.g., BTC, ETH)"},"name":{"type":"string","description":"Cryptocurrency name"},"contract":{"type":"string","description":"Token contract address (for ERC-20 tokens)"},"decimals":{"type":"integer","format":"int64","description":"Token decimals (number of decimal places)"},"blockchains":{"type":"array","items":{"type":"string"},"description":"List of supported blockchain names/slugs"}}}}}}
```

## The FiatCurrencyCapability object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"FiatCurrencyCapability":{"type":"object","properties":{"code":{"type":"string","description":"Fiat currency code (ISO 4217)"},"name":{"type":"string","description":"Fiat currency name"},"institution_id":{"type":"array","items":{"type":"string"},"description":"List of payment method slugs that support this currency (retrieved from active payment method options)"},"countries":{"type":"array","items":{"type":"string"},"description":"List of ISO 2-letter country codes where this currency is supported (retrieved from active payment method options)"},"onramp":{"type":"boolean","description":"Whether onramp (fiat to crypto) is supported. Currently set to true if there are any active payment method options for this currency.\nThis will be refined in future updates based on trade types and explicit direction configuration.\n"},"offramp":{"type":"boolean","description":"Whether offramp (crypto to fiat) is supported. Currently set to true if there are any active payment method options for this currency.\nThis will be refined in future updates based on trade types and explicit direction configuration.\n"}}}}}}
```

## The FiatCurrenciesResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"FiatCurrenciesResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FiatCurrencyCapability"}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"FiatCurrencyCapability":{"type":"object","properties":{"code":{"type":"string","description":"Fiat currency code (ISO 4217)"},"name":{"type":"string","description":"Fiat currency name"},"institution_id":{"type":"array","items":{"type":"string"},"description":"List of payment method slugs that support this currency (retrieved from active payment method options)"},"countries":{"type":"array","items":{"type":"string"},"description":"List of ISO 2-letter country codes where this currency is supported (retrieved from active payment method options)"},"onramp":{"type":"boolean","description":"Whether onramp (fiat to crypto) is supported. Currently set to true if there are any active payment method options for this currency.\nThis will be refined in future updates based on trade types and explicit direction configuration.\n"},"offramp":{"type":"boolean","description":"Whether offramp (crypto to fiat) is supported. Currently set to true if there are any active payment method options for this currency.\nThis will be refined in future updates based on trade types and explicit direction configuration.\n"}}}}}}
```

## The CorridorRateQuote object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CorridorRateQuote":{"type":"object","description":"One partner-type variant of a corridor rate (P2P or Licensed).\n","properties":{"rate":{"type":"number","format":"double","nullable":true,"description":"All-in fiat-per-USDT rate (platform fee already applied)."},"min_notional_fiat":{"type":"number","format":"double","nullable":true,"description":"Smallest amount accepted by any active offer in this variant, in the corridor's local currency. Set only when it exceeds the reference notional in dollar terms — i.e. the customer would need to size up to use this variant."}}}}}}
```

## The CorridorDirectionInfo object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CorridorDirectionInfo":{"type":"object","description":"Per-direction info for one fiat corridor. The whole object is\nomitted when no active offer exists in that direction. Either\n`p2p` or `licensed` (or both) will be present.\n","properties":{"supported":{"type":"boolean","description":"Always `true` when the object is present (the object is omitted otherwise). Reserved for future states where a corridor may be configured but temporarily without liquidity."},"p2p":{"$ref":"#/components/schemas/CorridorRateQuote"},"licensed":{"$ref":"#/components/schemas/CorridorRateQuote"}}},"CorridorRateQuote":{"type":"object","description":"One partner-type variant of a corridor rate (P2P or Licensed).\n","properties":{"rate":{"type":"number","format":"double","nullable":true,"description":"All-in fiat-per-USDT rate (platform fee already applied)."},"min_notional_fiat":{"type":"number","format":"double","nullable":true,"description":"Smallest amount accepted by any active offer in this variant, in the corridor's local currency. Set only when it exceeds the reference notional in dollar terms — i.e. the customer would need to size up to use this variant."}}}}}}
```

## The Corridor object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"Corridor":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"mid_market_rate":{"type":"number","format":"double","nullable":true,"description":"Open Exchange Rates reference rate (fiat per USDT) for this currency. Same value applies to both directions."},"mid_market_updated_at":{"type":"string","format":"date-time","nullable":true},"unigox_fee_pct":{"type":"number","format":"double","nullable":true,"description":"Cheapest active Unigox platform fee for this corridor, in percent. Already baked into every `rate` below."},"onramp":{"$ref":"#/components/schemas/CorridorDirectionInfo"},"offramp":{"$ref":"#/components/schemas/CorridorDirectionInfo"}}},"CorridorDirectionInfo":{"type":"object","description":"Per-direction info for one fiat corridor. The whole object is\nomitted when no active offer exists in that direction. Either\n`p2p` or `licensed` (or both) will be present.\n","properties":{"supported":{"type":"boolean","description":"Always `true` when the object is present (the object is omitted otherwise). Reserved for future states where a corridor may be configured but temporarily without liquidity."},"p2p":{"$ref":"#/components/schemas/CorridorRateQuote"},"licensed":{"$ref":"#/components/schemas/CorridorRateQuote"}}},"CorridorRateQuote":{"type":"object","description":"One partner-type variant of a corridor rate (P2P or Licensed).\n","properties":{"rate":{"type":"number","format":"double","nullable":true,"description":"All-in fiat-per-USDT rate (platform fee already applied)."},"min_notional_fiat":{"type":"number","format":"double","nullable":true,"description":"Smallest amount accepted by any active offer in this variant, in the corridor's local currency. Set only when it exceeds the reference notional in dollar terms — i.e. the customer would need to size up to use this variant."}}}}}}
```

## The SupportedCorridorsPayload object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"SupportedCorridorsPayload":{"type":"object","properties":{"notional_usdt":{"type":"number","format":"double"},"generated_at":{"type":"string","format":"date-time"},"currencies":{"type":"array","items":{"$ref":"#/components/schemas/Corridor"}}}},"Corridor":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"mid_market_rate":{"type":"number","format":"double","nullable":true,"description":"Open Exchange Rates reference rate (fiat per USDT) for this currency. Same value applies to both directions."},"mid_market_updated_at":{"type":"string","format":"date-time","nullable":true},"unigox_fee_pct":{"type":"number","format":"double","nullable":true,"description":"Cheapest active Unigox platform fee for this corridor, in percent. Already baked into every `rate` below."},"onramp":{"$ref":"#/components/schemas/CorridorDirectionInfo"},"offramp":{"$ref":"#/components/schemas/CorridorDirectionInfo"}}},"CorridorDirectionInfo":{"type":"object","description":"Per-direction info for one fiat corridor. The whole object is\nomitted when no active offer exists in that direction. Either\n`p2p` or `licensed` (or both) will be present.\n","properties":{"supported":{"type":"boolean","description":"Always `true` when the object is present (the object is omitted otherwise). Reserved for future states where a corridor may be configured but temporarily without liquidity."},"p2p":{"$ref":"#/components/schemas/CorridorRateQuote"},"licensed":{"$ref":"#/components/schemas/CorridorRateQuote"}}},"CorridorRateQuote":{"type":"object","description":"One partner-type variant of a corridor rate (P2P or Licensed).\n","properties":{"rate":{"type":"number","format":"double","nullable":true,"description":"All-in fiat-per-USDT rate (platform fee already applied)."},"min_notional_fiat":{"type":"number","format":"double","nullable":true,"description":"Smallest amount accepted by any active offer in this variant, in the corridor's local currency. Set only when it exceeds the reference notional in dollar terms — i.e. the customer would need to size up to use this variant."}}}}}}
```

## The SupportedCorridorsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"SupportedCorridorsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupportedCorridorsPayload"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"SupportedCorridorsPayload":{"type":"object","properties":{"notional_usdt":{"type":"number","format":"double"},"generated_at":{"type":"string","format":"date-time"},"currencies":{"type":"array","items":{"$ref":"#/components/schemas/Corridor"}}}},"Corridor":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"mid_market_rate":{"type":"number","format":"double","nullable":true,"description":"Open Exchange Rates reference rate (fiat per USDT) for this currency. Same value applies to both directions."},"mid_market_updated_at":{"type":"string","format":"date-time","nullable":true},"unigox_fee_pct":{"type":"number","format":"double","nullable":true,"description":"Cheapest active Unigox platform fee for this corridor, in percent. Already baked into every `rate` below."},"onramp":{"$ref":"#/components/schemas/CorridorDirectionInfo"},"offramp":{"$ref":"#/components/schemas/CorridorDirectionInfo"}}},"CorridorDirectionInfo":{"type":"object","description":"Per-direction info for one fiat corridor. The whole object is\nomitted when no active offer exists in that direction. Either\n`p2p` or `licensed` (or both) will be present.\n","properties":{"supported":{"type":"boolean","description":"Always `true` when the object is present (the object is omitted otherwise). Reserved for future states where a corridor may be configured but temporarily without liquidity."},"p2p":{"$ref":"#/components/schemas/CorridorRateQuote"},"licensed":{"$ref":"#/components/schemas/CorridorRateQuote"}}},"CorridorRateQuote":{"type":"object","description":"One partner-type variant of a corridor rate (P2P or Licensed).\n","properties":{"rate":{"type":"number","format":"double","nullable":true,"description":"All-in fiat-per-USDT rate (platform fee already applied)."},"min_notional_fiat":{"type":"number","format":"double","nullable":true,"description":"Smallest amount accepted by any active offer in this variant, in the corridor's local currency. Set only when it exceeds the reference notional in dollar terms — i.e. the customer would need to size up to use this variant."}}}}}}
```

## The PaymentField object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PaymentField":{"type":"object","properties":{"key":{"type":"string","description":"Field identifier/key"},"label":{"type":"string","description":"Human-readable field label"},"type":{"type":"string","description":"Field input type (text, number, select, etc.)"},"required":{"type":"boolean","description":"Whether this field is required"},"pattern":{"type":"string","description":"Regex pattern for validation (optional)"},"placeholder":{"type":"string","description":"Placeholder text for input (optional)"},"lookup":{"type":"boolean","description":"Whether field can be used for lookup (optional)"},"options":{"type":"array","description":"Options for select fields (optional)","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}}}}}}
```

## The Rails object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"Rails":{"type":"object","properties":{"slug":{"type":"string","description":"Payment rail slug identifier"},"name":{"type":"string","description":"Payment rail name"},"institution_required":{"type":"boolean","description":"Whether institution (bank) selection is required by the rail itself. In the current partner API, omission of `institution_id` is explicitly supported only for `iban-sepa` and `nip-nigeria`."},"institution_lookup_key":{"type":"string","nullable":true,"description":"Lookup key for institution search, e.g., ifsc or sort_code"},"currencies":{"type":"array","items":{"type":"string"},"description":"List of supported fiat currency codes"},"settlement":{"type":"object","nullable":true,"description":"Settlement information","properties":{"speed":{"type":"string","enum":["INSTANT","SAME_DAY","NEXT_DAY","STANDARD"],"description":"Settlement speed"},"typical_minutes":{"type":"integer","description":"Typical settlement time in minutes"},"note":{"type":"string","nullable":true,"description":"Optional note about settlement"}}},"limits":{"type":"object","nullable":true,"description":"Transaction limits","properties":{"min_amount":{"type":"number","nullable":true,"description":"Minimum transaction amount"},"max_amount":{"type":"number","nullable":true,"description":"Maximum transaction amount (null = no limit)"},"max_per_transaction":{"type":"number","nullable":true,"description":"Maximum per transaction (null = no limit)"}}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/PaymentField"},"description":"Required fields for payment details input"}}},"PaymentField":{"type":"object","properties":{"key":{"type":"string","description":"Field identifier/key"},"label":{"type":"string","description":"Human-readable field label"},"type":{"type":"string","description":"Field input type (text, number, select, etc.)"},"required":{"type":"boolean","description":"Whether this field is required"},"pattern":{"type":"string","description":"Regex pattern for validation (optional)"},"placeholder":{"type":"string","description":"Placeholder text for input (optional)"},"lookup":{"type":"boolean","description":"Whether field can be used for lookup (optional)"},"options":{"type":"array","description":"Options for select fields (optional)","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}}}}}}
```

## The PaymentCapabilityResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PaymentCapabilityResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","required":["country","direction","rails"],"properties":{"country":{"type":"string","description":"Country code used in the query"},"currency":{"type":"string","description":"Currency code (from query parameter or first rail)"},"direction":{"type":"string","enum":["onramp","offramp"],"description":"Transaction direction"},"rails":{"type":"array","items":{"$ref":"#/components/schemas/Rails"},"description":"List of available payment rails"},"links":{"type":"object","additionalProperties":{"type":"string"},"description":"Related API endpoints"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"Rails":{"type":"object","properties":{"slug":{"type":"string","description":"Payment rail slug identifier"},"name":{"type":"string","description":"Payment rail name"},"institution_required":{"type":"boolean","description":"Whether institution (bank) selection is required by the rail itself. In the current partner API, omission of `institution_id` is explicitly supported only for `iban-sepa` and `nip-nigeria`."},"institution_lookup_key":{"type":"string","nullable":true,"description":"Lookup key for institution search, e.g., ifsc or sort_code"},"currencies":{"type":"array","items":{"type":"string"},"description":"List of supported fiat currency codes"},"settlement":{"type":"object","nullable":true,"description":"Settlement information","properties":{"speed":{"type":"string","enum":["INSTANT","SAME_DAY","NEXT_DAY","STANDARD"],"description":"Settlement speed"},"typical_minutes":{"type":"integer","description":"Typical settlement time in minutes"},"note":{"type":"string","nullable":true,"description":"Optional note about settlement"}}},"limits":{"type":"object","nullable":true,"description":"Transaction limits","properties":{"min_amount":{"type":"number","nullable":true,"description":"Minimum transaction amount"},"max_amount":{"type":"number","nullable":true,"description":"Maximum transaction amount (null = no limit)"},"max_per_transaction":{"type":"number","nullable":true,"description":"Maximum per transaction (null = no limit)"}}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/PaymentField"},"description":"Required fields for payment details input"}}},"PaymentField":{"type":"object","properties":{"key":{"type":"string","description":"Field identifier/key"},"label":{"type":"string","description":"Human-readable field label"},"type":{"type":"string","description":"Field input type (text, number, select, etc.)"},"required":{"type":"boolean","description":"Whether this field is required"},"pattern":{"type":"string","description":"Regex pattern for validation (optional)"},"placeholder":{"type":"string","description":"Placeholder text for input (optional)"},"lookup":{"type":"boolean","description":"Whether field can be used for lookup (optional)"},"options":{"type":"array","description":"Options for select fields (optional)","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}}}}}}
```

## The InstitutionBranch object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"InstitutionBranch":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Branch code (e.g., IFSC, sort code)"},"name":{"type":"string","description":"Branch name"},"address":{"type":"string","description":"Branch address"}}}}}}
```

## The Institution object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"Institution":{"type":"object","properties":{"id":{"type":"string","description":"Institution identifier"},"name":{"type":"string","description":"Institution name"},"type":{"type":"string","description":"Institution type (e.g., BANK, WALLET)"},"code":{"type":"string","nullable":true,"description":"Institution code for lookup (e.g., IFSC, sort code)"},"branch":{"$ref":"#/components/schemas/InstitutionBranch"},"supported_rails":{"type":"array","items":{"type":"string"},"description":"List of payment rail slugs this institution supports"}}},"InstitutionBranch":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Branch code (e.g., IFSC, sort code)"},"name":{"type":"string","description":"Branch name"},"address":{"type":"string","description":"Branch address"}}}}}}
```

## The Pagination object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Items per page"},"offset":{"type":"integer","description":"Current offset"}}}}}}
```

## The InstitutionsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"InstitutionsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","required":["institutions","pagination"],"properties":{"institutions":{"type":"array","items":{"$ref":"#/components/schemas/Institution"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"Institution":{"type":"object","properties":{"id":{"type":"string","description":"Institution identifier"},"name":{"type":"string","description":"Institution name"},"type":{"type":"string","description":"Institution type (e.g., BANK, WALLET)"},"code":{"type":"string","nullable":true,"description":"Institution code for lookup (e.g., IFSC, sort code)"},"branch":{"$ref":"#/components/schemas/InstitutionBranch"},"supported_rails":{"type":"array","items":{"type":"string"},"description":"List of payment rail slugs this institution supports"}}},"InstitutionBranch":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Branch code (e.g., IFSC, sort code)"},"name":{"type":"string","description":"Branch name"},"address":{"type":"string","description":"Branch address"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Items per page"},"offset":{"type":"integer","description":"Current offset"}}}}}}
```

## The SupportedPair object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"SupportedPair":{"type":"object","properties":{"crypto_currency_code":{"type":"string","description":"Cryptocurrency code (e.g., USDC, BTC)"},"fiat_currency_code":{"type":"string","description":"Fiat currency code (e.g., USD, EUR)"},"type":{"type":"string","enum":["BUY","SELL"],"description":"Trading pair type - BUY (fiat to crypto) or SELL (crypto to fiat)"}}}}}}
```

## The SupportedPairsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"SupportedPairsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SupportedPair"}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"SupportedPair":{"type":"object","properties":{"crypto_currency_code":{"type":"string","description":"Cryptocurrency code (e.g., USDC, BTC)"},"fiat_currency_code":{"type":"string","description":"Fiat currency code (e.g., USD, EUR)"},"type":{"type":"string","enum":["BUY","SELL"],"description":"Trading pair type - BUY (fiat to crypto) or SELL (crypto to fiat)"}}}}}}
```

## The CreateUserResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CreateUserResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the user. Use this value in all subsequent API calls."},"email":{"type":"string","format":"email"},"kyc_status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","VERIFIED","VERIFICATION_REJECTED"]},"created_at":{"type":"string","format":"date-time"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}}}
```

## The GetUserResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"GetUserResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the user. Use this value in all subsequent API calls."},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"kyc":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","VERIFIED","VERIFICATION_REJECTED"]},"kyc_method":{"type":"string","enum":["direct_data","external_token","handoff"],"description":"KYC submission method used"},"first_name":{"type":"string","description":"User's first name from KYC data"},"last_name":{"type":"string","description":"User's last name from KYC data"},"country_code":{"type":"string","description":"User's country code (ISO 2-letter) from KYC data"},"rejection_reason":{"type":"string","nullable":true,"description":"Reason for KYC rejection (if status is VERIFICATION_REJECTED)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp for KYC status"}}},"payment_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rail":{"type":"string"},"currency":{"type":"string"},"institution_name":{"type":"string","nullable":true},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","additionalProperties":true}}}}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}}}
```

## The KYCSubmitDirectData object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"KYCSubmitDirectData":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["direct_data"]},"data":{"type":"object","required":["pii"],"properties":{"pii":{"type":"object","required":["first_name","last_name","country_code"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"country_code":{"type":"string"},"dob":{"type":"string","format":"date"},"middle_name":{"type":"string"},"phone_number":{"type":"string","description":"E.164 format"},"id_number":{"type":"string"},"id_type":{"type":"string","enum":["NATIONAL_ID","DRIVER_LICENSE","PASSPORT"]},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City. Required for EUR/AUD/GBP offramp (auto-populates into payment details)."},"postal_code":{"type":"string"}}}}}}}}}}
```

## The KYCSubmitExternalToken object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"KYCSubmitExternalToken":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["external_token"]},"data":{"type":"object","required":["provider"],"description":"Provider-specific fields:\n- SumSub: requires `token` (SumSub share token)\n- Persona: requires `inquiry_id` (Persona inquiry ID, e.g. inq_xxx)\n","properties":{"provider":{"type":"string","enum":["sumsub","persona"],"description":"KYC provider name"},"token":{"type":"string","description":"SumSub share token (required when provider=sumsub)"},"inquiry_id":{"type":"string","description":"Persona inquiry ID (required when provider=persona). This is the inq_xxx identifier returned by Persona when the inquiry was created."}}}}}}}}
```

## The KYCSubmitHandoff object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"KYCSubmitHandoff":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["handoff"]},"data":{"type":"object","properties":{"pii":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"country_code":{"type":"string"}}}}}}}}}}
```

## The KYCSubmitResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"KYCSubmitResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"kyc_status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","VERIFIED","VERIFICATION_REJECTED"]},"message":{"type":"string"},"verification_url":{"type":"string","format":"uri","nullable":true,"description":"Verification URL (only returned for handoff method)"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}}}
```

## The VerificationStatusResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"VerificationStatusResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_STARTED","PENDING","IN_PROGRESS","COMPLETED","VERIFIED","FAILED","VERIFICATION_REJECTED"],"description":"Current verification status.\n\nRecommended partner interpretation:\n- `NOT_STARTED`, `PENDING`, `IN_PROGRESS` — still processing\n- `VERIFIED` — approved / successful verification\n- `VERIFICATION_REJECTED` — completed with rejection\n- `FAILED` — terminal error\n- `COMPLETED` — provider workflow completed, but partners should not treat this alone as approval; wait for `VERIFIED` to consider the user approved\n"},"verification_url":{"type":"string","format":"uri","nullable":true,"description":"Verification URL (for handoff method)"},"verification_seconds_left":{"type":"integer","nullable":true,"description":"Seconds remaining for verification session (if applicable)"},"provider_messages":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Provider-specific messages or rejection reasons"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}}}
```

## The CreatePaymentDetailsRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CreatePaymentDetailsRequest":{"description":"Conditional request schema for partner payment details. `institution_id` may be omitted only for `iban-sepa` and `nip-nigeria`.","oneOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestInstitutionOptional"},{"$ref":"#/components/schemas/CreatePaymentDetailsRequestInstitutionRequired"}]},"CreatePaymentDetailsRequestInstitutionOptional":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","properties":{"rail":{"type":"string","enum":["iban-sepa","nip-nigeria"],"description":"Payment rail identifier for rails that support omission of `institution_id`"},"institution_id":{"type":"string","description":"Optional for `iban-sepa` and `nip-nigeria`.\nIf omitted, the backend assigns the generic `other-bank` payment method automatically.\n"}}}]},"CreatePaymentDetailsRequestBase":{"type":"object","required":["currency","rail","details"],"properties":{"currency":{"type":"string","description":"ISO 3-letter fiat currency code (e.g., INR, EUR, USD)"},"rail":{"type":"string","description":"Payment rail identifier (e.g., \"upi-india\", \"iban-sepa\", \"imps-india\")"},"details":{"type":"object","description":"Payment details object with fields specific to the payment network (e.g., account_number, vpa, iban, full_name)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}},"CreatePaymentDetailsRequestInstitutionRequired":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","required":["institution_id"],"properties":{"rail":{"type":"string","description":"Payment rail identifier for rails that require institution selection","not":{"enum":["iban-sepa","nip-nigeria"]}},"institution_id":{"type":"string","description":"Institution (payment method) identifier - our internal slug (e.g., \"wise\", \"hdfc-bank\", \"revolut\", \"uala\", \"banco-santander-argentina\").\nRequired for all rails except `iban-sepa` and `nip-nigeria`.\nIf omitted for any other rail, the API returns a validation error.\nFor rails with multiple formats (e.g., CVU/CBU), the format is automatically determined based on the payment method type of this institution.\n"}}}]}}}}
```

## The CreatePaymentDetailsRequestBase object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CreatePaymentDetailsRequestBase":{"type":"object","required":["currency","rail","details"],"properties":{"currency":{"type":"string","description":"ISO 3-letter fiat currency code (e.g., INR, EUR, USD)"},"rail":{"type":"string","description":"Payment rail identifier (e.g., \"upi-india\", \"iban-sepa\", \"imps-india\")"},"details":{"type":"object","description":"Payment details object with fields specific to the payment network (e.g., account_number, vpa, iban, full_name)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}}}}}
```

## The CreatePaymentDetailsRequestInstitutionOptional object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CreatePaymentDetailsRequestInstitutionOptional":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","properties":{"rail":{"type":"string","enum":["iban-sepa","nip-nigeria"],"description":"Payment rail identifier for rails that support omission of `institution_id`"},"institution_id":{"type":"string","description":"Optional for `iban-sepa` and `nip-nigeria`.\nIf omitted, the backend assigns the generic `other-bank` payment method automatically.\n"}}}]},"CreatePaymentDetailsRequestBase":{"type":"object","required":["currency","rail","details"],"properties":{"currency":{"type":"string","description":"ISO 3-letter fiat currency code (e.g., INR, EUR, USD)"},"rail":{"type":"string","description":"Payment rail identifier (e.g., \"upi-india\", \"iban-sepa\", \"imps-india\")"},"details":{"type":"object","description":"Payment details object with fields specific to the payment network (e.g., account_number, vpa, iban, full_name)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}}}}}
```

## The CreatePaymentDetailsRequestInstitutionRequired object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CreatePaymentDetailsRequestInstitutionRequired":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","required":["institution_id"],"properties":{"rail":{"type":"string","description":"Payment rail identifier for rails that require institution selection","not":{"enum":["iban-sepa","nip-nigeria"]}},"institution_id":{"type":"string","description":"Institution (payment method) identifier - our internal slug (e.g., \"wise\", \"hdfc-bank\", \"revolut\", \"uala\", \"banco-santander-argentina\").\nRequired for all rails except `iban-sepa` and `nip-nigeria`.\nIf omitted for any other rail, the API returns a validation error.\nFor rails with multiple formats (e.g., CVU/CBU), the format is automatically determined based on the payment method type of this institution.\n"}}}]},"CreatePaymentDetailsRequestBase":{"type":"object","required":["currency","rail","details"],"properties":{"currency":{"type":"string","description":"ISO 3-letter fiat currency code (e.g., INR, EUR, USD)"},"rail":{"type":"string","description":"Payment rail identifier (e.g., \"upi-india\", \"iban-sepa\", \"imps-india\")"},"details":{"type":"object","description":"Payment details object with fields specific to the payment network (e.g., account_number, vpa, iban, full_name)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}}}}}
```

## The PaymentProfile object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}}}}}
```

## The CreatePaymentDetailsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"CreatePaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentProfile"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}}}}}
```

## The GetPaymentDetailsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"GetPaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProfile"},"description":"List of all payment profiles for the user"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}}}}}
```

## The SlippageTolerance object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"SlippageTolerance":{"type":"object","properties":{"type":{"type":"string","enum":["percent","amount","fiat"],"description":"Tolerance type:\n- `percent` — percentage of the quoted rate (e.g., 1.5 = 1.5%)\n- `amount` — absolute fiat amount (e.g., 50.00 = 50 NGN)\n- `fiat` — alias of `amount`\n"},"value":{"type":"number","format":"double","description":"Tolerance value (percentage or fiat amount depending on type)"}}}}}}
```

## The LiquidityPair object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"LiquidityPair":{"type":"object","required":["crypto_currency_code","fiat_currency_code","trade_type","min_amount","max_amount","min_amount_usd","max_amount_usd","payment_methods"],"properties":{"crypto_currency_code":{"type":"string","description":"Cryptocurrency code (e.g. USDC, BTC)"},"fiat_currency_code":{"type":"string","description":"Fiat currency code (ISO 4217)"},"trade_type":{"type":"string","enum":["BUY","SELL"],"description":"Partner-facing trade direction.\n`SELL` — partner sells crypto and receives fiat (off-ramp).\n`BUY` — partner buys crypto by sending fiat (on-ramp).\n"},"min_amount":{"type":"number","format":"double","description":"Minimum fiat amount accepted across all eligible offers, in the pair's native fiat currency"},"max_amount":{"type":"number","format":"double","description":"Maximum fiat amount accepted across all eligible offers, in the pair's native fiat currency"},"min_amount_usd":{"type":"number","format":"double","description":"Minimum fiat amount converted to USD"},"max_amount_usd":{"type":"number","format":"double","description":"Maximum fiat amount converted to USD"},"payment_methods":{"type":"array","items":{"type":"string"},"description":"Deduplicated, alphabetically sorted list of payment method slugs available for this pair"}}}}}}
```

## The PartnerPriceEstimateRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerPriceEstimateRequest":{"type":"object","required":["crypto_currency","fiat_currency"],"oneOf":[{"required":["crypto_amount"]},{"required":["fiat_amount"]}],"properties":{"crypto_currency":{"type":"string","description":"Cryptocurrency code (e.g., USDT, USDC)"},"fiat_currency":{"type":"string","description":"Target fiat currency code (e.g., NGN, USD, EUR)"},"crypto_amount":{"type":"string","description":"Crypto amount to estimate from. Provide exactly one of crypto_amount or fiat_amount."},"fiat_amount":{"type":"string","description":"Fiat amount to estimate from. Provide exactly one of crypto_amount or fiat_amount."},"payment_method_slug":{"type":"string","description":"Optional payment method slug filter to narrow routing"},"payment_network_slug":{"type":"string","description":"Optional payment network slug filter to narrow routing"},"provider_scope":{"type":"string","description":"Optional provider scope filter; defaults to all","enum":["all","licensed_only","p2p_only"]},"country_code":{"type":"string","description":"Optional ISO country code (alpha-2) used for fee/routing context"}}}}}}
```

## The PartnerPriceEstimateResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerPriceEstimateResponse":{"type":"object","properties":{"rate":{"type":"string","description":"Indicative crypto-to-fiat exchange rate"},"crypto_amount":{"type":"string","description":"Estimated total crypto amount (includes fees)"},"fiat_amount":{"type":"string","description":"Estimated fiat amount"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"payment_method_slug":{"type":"string","description":"Matched payment method slug used for estimate"},"payment_network_slug":{"type":"string","description":"Matched payment network slug used for estimate"},"provider_scope":{"type":"string","description":"Applied provider scope"},"is_indicative":{"type":"boolean","description":"True when response is an estimate and not a reserving quote"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}}}}}
```

## The PartnerQuoteRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerQuoteRequest":{"type":"object","required":["user_uuid","payment_details_id","crypto_currency","fiat_currency"],"oneOf":[{"required":["crypto_amount"]},{"required":["fiat_amount"]}],"properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the end-user (returned by `POST /partner/users` as `id`)"},"payment_details_id":{"type":"integer","format":"int64","description":"ID of a previously created payment profile for the user"},"crypto_currency":{"type":"string","description":"Cryptocurrency code (e.g., USDT, USDC)"},"crypto_amount":{"type":"string","description":"Amount of crypto to sell (standard units, e.g., \"100.00\" for 100 USDT).\nProvide exactly one of `crypto_amount` or `fiat_amount`.\nWhen provided, the order is **crypto-anchored** — exact crypto cost is guaranteed, fiat payout varies by rate at settlement.\n"},"fiat_amount":{"type":"string","description":"Exact fiat amount the recipient will receive (e.g., \"500000\" for 500,000 NGN).\nProvide exactly one of `crypto_amount` or `fiat_amount`.\nWhen provided, the order is **fiat-anchored** — exact fiat delivery is guaranteed, crypto cost may vary within a 1.20× safety bound.\nFor integer-minor-unit currencies (NGN, UGX, TZS, KES, GHS), must be a whole number.\n"},"fiat_currency":{"type":"string","description":"Target fiat currency code (e.g., NGN, USD, EUR)"},"rail":{"type":"string","description":"Optional rail hint; must be compatible with payment details if provided"},"route":{"type":"string","description":"Optional route hint; must be compatible with payment details if provided"},"provider_scope":{"type":"string","description":"Optional provider scope filter; defaults to all","enum":["all","licensed_only","p2p_only"]},"slippage_tolerance":{"allOf":[{"$ref":"#/components/schemas/SlippageTolerance"}],"description":"Optional. Maximum tolerated price movement between `/quote` and `/initiate`,\nand between `/initiate` and vendor acceptance. When omitted, the default is\n`percent` / `0` — any rate movement returns `PRICE_CHANGED_REQUOTE` and the\npartner must request a fresh quote. Set this to opt in to silent execution\nfor small market movements.\n"},"has_fiat_settlement_notification":{"type":"boolean","description":"When `true`, only match liquidity providers that send fiat settlement\nnotifications. Orders from these providers complete automatically when\nfiat is delivered. When omitted or `false`, all providers are eligible.\n"}}},"SlippageTolerance":{"type":"object","properties":{"type":{"type":"string","enum":["percent","amount","fiat"],"description":"Tolerance type:\n- `percent` — percentage of the quoted rate (e.g., 1.5 = 1.5%)\n- `amount` — absolute fiat amount (e.g., 50.00 = 50 NGN)\n- `fiat` — alias of `amount`\n"},"value":{"type":"number","format":"double","description":"Tolerance value (percentage or fiat amount depending on type)"}}}}}}
```

## The PartnerQuoteResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerQuoteResponse":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid","description":"Unique quote identifier — use this to initiate the order"},"anchor_type":{"type":"string","enum":["crypto","fiat"],"description":"Indicates which amount is guaranteed at settlement.\n- `crypto` — `crypto_amount` is exact; `fiat_amount` may vary by Switch rate at settlement.\n- `fiat` — `fiat_amount` is exact; `crypto_amount` may vary within a 1.20× safety bound.\n"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate at quote time"},"crypto_amount":{"type":"string","description":"Total crypto amount the user sends (includes all fees)"},"fiat_amount":{"type":"string","description":"Fiat amount the recipient receives"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"payment_details_id":{"type":"integer","format":"int64","description":"Payment details ID used for this quote"},"payment_method_id":{"type":"integer","format":"int64","description":"Matched payment method ID"},"payment_network_id":{"type":"integer","format":"int64","description":"Matched payment network ID"},"expires_at":{"type":"string","format":"date-time","description":"Quote expiration timestamp (30 seconds from creation)"},"has_fiat_settlement_notification":{"type":"boolean","description":"Whether the matched liquidity provider sends fiat settlement notifications.\nWhen `true`, the order will complete automatically when fiat is delivered\nto the recipient. When `false`, you must call `confirm-fiat-received`.\nYou can call `confirm-fiat-received` at any time regardless of this value.\n"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}}}}}
```

## The PartnerInitiateRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerInitiateRequest":{"type":"object","required":["quote_id"],"properties":{"quote_id":{"type":"string","format":"uuid","description":"Quote ID from the quote endpoint. Payment details are taken from the quote."},"reference_id":{"type":"string","description":"Optional partner-supplied external reference ID (e.g. your internal order ID). Stored on the order and echoed back in responses."}}}}}}
```

## The PartnerInitiateResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerInitiateResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier for tracking"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"quote_id":{"type":"string","format":"uuid","description":"Quote ID that was consumed"},"reference_id":{"type":"string","nullable":true,"description":"Partner-supplied external reference ID (echoed from initiate request)"},"order_type":{"type":"string","enum":["offramp","onramp"],"description":"Direction of the order"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"}},"created_at":{"type":"string","format":"date-time"}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow, partner must confirm payment sent\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units)"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change"}}}}}}
```

## The PartnerOrderResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerOrderResponse":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Unique order identifier"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"next_action":{"type":"string","nullable":true,"description":"The action the partner **must** perform to advance the order. `null` means\nno action is required from the partner at this stage — the order is waiting\nfor the counterparty or for an automated system step.\n\nPossible values:\n- `authorize_crypto_transfer` — partner must authorize escrow funding\n- `confirm_fiat_received` — partner must confirm they received the fiat payment\n- `request_new_quote` — price changed, partner must request a new quote\n- `update_kyc_address` — address fields are required for EUR/AUD/GBP payouts; see `action_required` for the endpoint and fields to submit\n- `null` — no required action (waiting for buyer or system)\n","enum":["authorize_crypto_transfer","confirm_fiat_received","request_new_quote","update_kyc_address",null]},"action_required":{"type":"object","nullable":true,"description":"Present when the order needs partner intervention before it can proceed.\nContains machine-readable type, human-readable message, the API endpoint to call,\nand the fields to provide. Null/omitted when no action is needed.\n","required":["type","message"],"properties":{"type":{"type":"string","description":"Machine-readable action identifier"},"message":{"type":"string","description":"Human-readable explanation of what is needed and why"},"endpoint":{"type":"string","description":"API endpoint to call to resolve this action"},"fields":{"type":"array","description":"Fields the partner needs to provide","items":{"type":"object","required":["field","label"],"properties":{"field":{"type":"string","description":"API field name"},"label":{"type":"string","description":"Human-readable description of the field"}}}}}},"allowed_actions":{"type":"array","items":{"type":"string"},"description":"List of API actions the partner **can** perform at the current status. An action\nmay be present here even when `next_action` is `null` — meaning it is optional.\n\nNotable case: `confirm-fiat-received` appears at both `crypto_received` and\n`awaiting_fiat_received_confirmation`. At `crypto_received` it is a **fast-track**:\nif you already know the fiat has arrived via your own systems, you can confirm\nimmediately. Otherwise, wait for the buyer's proof flow to complete — the order\nwill reach `awaiting_fiat_received_confirmation` automatically.\n\nStatus-to-actions mapping:\n- `created` → `[\"cancel\"]`\n- `awaiting_liquidity_provider` → `[\"cancel\"]`\n- `awaiting_crypto_transfer_authorization` → `[\"authorize-crypto-transfer\", \"cancel\"]`\n- `crypto_transfer_authorization_pending` → `[\"cancel\"]`\n- `crypto_received` → `[\"confirm-fiat-received\"]` (optional fast-track)\n- `fiat_payment_started` → `[\"confirm-fiat-received\"]` (optional fast-track after buyer proof submission)\n- `awaiting_fiat_received_confirmation` → `[\"confirm-fiat-received\"]` (required)\n- `fiat_received_confirmed`, `crypto_release_pending`, `completed`, `cancelled`, `failed` → `[]`\n"},"crypto_transfer_authorization_seconds_left":{"type":"integer","format":"int64","nullable":true,"description":"Remaining seconds to authorize crypto transfer while order is in\n`awaiting_crypto_transfer_authorization` / `crypto_transfer_authorization_pending`.\n`null` for all other statuses.\n"},"amounts":{"$ref":"#/components/schemas/PartnerOrderAmounts"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEntry"},"description":"Chronological list of status changes"},"has_fiat_settlement_notification":{"type":"boolean","description":"Whether the matched liquidity provider sends fiat settlement notifications.\nWhen `true`, the order will complete automatically when fiat is delivered.\nWhen `false`, you must call `confirm-fiat-received`. You can call\n`confirm-fiat-received` at any time regardless of this value.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"order_type":{"type":"string","nullable":true,"description":"Order type. Present for on-ramp orders. Absent for off-ramp orders.\n- `onramp` — buy crypto with fiat\n"},"vendor_payment_details":{"type":"object","nullable":true,"description":"Vendor's payment details for the end-user to send fiat to.\nPresent only for on-ramp orders at `awaiting_fiat_transfer` status and beyond.\n","properties":{"payment_method_name":{"type":"string"},"payment_network_name":{"type":"string"},"details":{"type":"object","description":"Payment method-specific fields (e.g. account_number, phone)"}}},"payment_request":{"type":"boolean","nullable":true,"description":"`true` if the vendor uses payment request flow — the partner must call\n`submit-payer-details` before `confirm-payment-sent`.\n"},"send_out_tx_hash":{"type":"string","nullable":true,"description":"Destination-chain transaction hash after a send-out completes.\nPresent only for on-ramp orders with `send_out_completed` status.\n"}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow, partner must confirm payment sent\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","send_out_pending","send_out_completed","send_out_failed"]},"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units)"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}},"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change"}}}}}}
```

## The PartnerOrderAmounts object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerOrderAmounts":{"type":"object","properties":{"crypto_amount":{"type":"string","description":"Total crypto amount (standard units)"},"fiat_amount":{"type":"string","description":"Fiat amount the user receives"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"rate":{"type":"string","description":"Crypto-to-fiat exchange rate"}}}}}}
```

## The FeeBreakdown object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}}}}}
```

## The PartnerOrderStatus object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow, partner must confirm payment sent\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","send_out_pending","send_out_completed","send_out_failed"]}}}}
```

## The TimelineEntry object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"TimelineEntry":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"timestamp":{"type":"string","format":"date-time","description":"When this status was reached"},"description":{"type":"string","description":"Human-readable description of the status change"}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow, partner must confirm payment sent\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","send_out_pending","send_out_completed","send_out_failed"]}}}}
```

## The RegisterWebhookRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"RegisterWebhookRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL that will receive webhook events"}}}}}}
```

## The WebhookConfigResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"WebhookConfigResponse":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Currently configured webhook URL (null if not set)"},"enabled":{"type":"boolean","description":"Whether webhook delivery is active"}}}}}}
```

## The WebhookTestPingResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"WebhookTestPingResponse":{"type":"object","properties":{"delivered":{"type":"boolean","description":"Whether the test event was delivered successfully"},"http_status":{"type":"integer","description":"HTTP status code returned by the webhook endpoint"}}}}}}
```

## The WebhookEventPayload object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"WebhookEventPayload":{"type":"object","description":"Payload shape delivered to your webhook URL on each order status change","properties":{"event_id":{"type":"string","description":"Unique event identifier for de-duplication"},"event_type":{"type":"string","description":"Event type (always `order.status.changed`)"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the event was created"},"data":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid","description":"Partner order UUID"},"status":{"$ref":"#/components/schemas/PartnerOrderStatus"},"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the end-user (from user creation)"},"crypto_amount":{"type":"string","description":"Total crypto amount including fees"},"crypto_currency":{"type":"string","description":"Cryptocurrency code"},"fiat_amount":{"type":"string","description":"Fiat amount"},"fiat_currency":{"type":"string","description":"Fiat currency code"},"provider":{"type":"string","description":"Liquidity provider type","enum":["p2p","licensed"]},"payment_details_id":{"type":"string","description":"Payment details ID used for the order"}}}}},"PartnerOrderStatus":{"type":"string","description":"Order status.\n\n**Off-ramp statuses (crypto → fiat):**\n- `created` — order created, quote locked\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_crypto_transfer_authorization` — partner must authorize crypto transfer via EIP-712 signature\n- `crypto_transfer_authorization_pending` — authorization submitted, awaiting on-chain confirmation\n- `crypto_received` — crypto locked in escrow\n- `fiat_payment_started` — buyer submitted fiat payment proof\n- `awaiting_fiat_received_confirmation` — waiting for partner to confirm fiat receipt\n- `fiat_received_confirmed` — fiat confirmed, crypto release pending\n- `crypto_release_pending` — escrow release in progress\n- `completed` — order fully completed\n- `cancelled` — order cancelled\n- `failed` — terminal error\n- `price_changed_requote_needed` — slippage exceeded at initiation (not a trade status)\n\n**On-ramp statuses (fiat → crypto):**\n- `awaiting_liquidity_provider` — order initiated, waiting for vendor acceptance\n- `awaiting_vendor_escrow_funding` — vendor accepted, funding escrow with crypto\n- `awaiting_fiat_transfer` — crypto locked in escrow, partner must confirm payment sent\n- `fiat_transfer_pending` — fiat payment confirmed, awaiting vendor confirmation of receipt\n- `completed` — vendor confirmed fiat received, crypto released to end-user wallet\n- `cancelled` — order cancelled\n- `failed` — escrow error\n\n**On-ramp send-out statuses (optional post-trade cross-chain transfer):**\n\n> After an on-ramp order reaches `completed`, the partner may optionally initiate a\n> **send-out** — a cross-chain transfer of the received crypto to a destination network\n> (e.g. XAI → Arbitrum). This is an additional flow and does not affect the core trade lifecycle.\n> The `completed` status reflects that the trade itself is done; send-out statuses track\n> the subsequent cross-chain transfer only.\n\n- `send_out_pending` — send-out initiated, cross-chain transfer in progress\n- `send_out_completed` — cross-chain transfer successfully delivered to destination\n- `send_out_failed` — cross-chain transfer failed; the on-ramp trade itself remains completed\n","enum":["created","awaiting_liquidity_provider","awaiting_crypto_transfer_authorization","crypto_transfer_authorization_pending","crypto_received","fiat_payment_started","awaiting_fiat_received_confirmation","fiat_received_confirmed","crypto_release_pending","awaiting_vendor_escrow_funding","awaiting_fiat_transfer","fiat_transfer_pending","completed","cancelled","failed","price_changed_requote_needed","send_out_pending","send_out_completed","send_out_failed"]}}}}
```

## The PartnerOnRampQuoteRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerOnRampQuoteRequest":{"type":"object","required":["user_uuid","fiat_currency","crypto_currency"],"oneOf":[{"required":["fiat_amount"]},{"required":["crypto_amount"]}],"properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the end-user (returned by `POST /partner/users` as `id`)"},"fiat_amount":{"type":"string","description":"Fiat amount the end-user will send. Provide exactly one of fiat_amount or crypto_amount."},"crypto_amount":{"type":"string","description":"Crypto amount to receive. Provide exactly one of fiat_amount or crypto_amount."},"fiat_currency":{"type":"string","description":"Source fiat currency code (ISO 4217)"},"crypto_currency":{"type":"string","description":"Target cryptocurrency code (e.g., USDT, USDC)"},"payment_method_slug":{"type":"string","description":"Optional payment method slug to narrow routing"},"payment_network_slug":{"type":"string","description":"Optional payment network slug to narrow routing"},"provider_scope":{"type":"string","description":"Optional provider scope filter; defaults to all","enum":["all","licensed_only","p2p_only"]},"country_code":{"type":"string","description":"Optional ISO 2-letter country code for fee/routing context"}}}}}}
```

## The PartnerOnRampQuoteResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerOnRampQuoteResponse":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid","description":"Unique quote identifier — use this to initiate the order"},"rate":{"type":"string","description":"Fiat-to-crypto exchange rate (fiat units per 1 crypto unit)"},"crypto_amount":{"type":"string","description":"Total crypto amount the end-user will receive (net of fees)"},"fiat_amount":{"type":"string","description":"Fiat amount the end-user sends"},"fee_breakdown":{"$ref":"#/components/schemas/FeeBreakdown"},"payment_method_slug":{"type":"string","description":"Matched payment method slug used for this quote"},"payment_network_slug":{"type":"string","description":"Matched payment network slug used for this quote"},"expires_at":{"type":"string","format":"date-time","description":"Quote expiration timestamp (60 seconds from creation)"}}},"FeeBreakdown":{"type":"object","description":"Transparent breakdown of all fee components (amounts in crypto)","properties":{"platform_fee":{"type":"string","description":"Platform fee in crypto"},"platform_fee_pct":{"type":"number","format":"double","description":"Platform fee as a percentage"},"partner_fee":{"type":"string","description":"Partner's fee markup in crypto (0 until partner fee dashboard is available)"},"partner_fee_pct":{"type":"number","format":"double","description":"Partner's fee percentage (0 until partner fee dashboard is available)"},"total_fee":{"type":"string","description":"Total fee in crypto (platform_fee + partner_fee)"}}}}}}
```

## The SubmitPayerDetailsRequest object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"SubmitPayerDetailsRequest":{"type":"object","description":"Submit the payer's payment details for a `payment_request` on-ramp order.\nProvide exactly one of `payment_details_id` (saved profile) or `payment_details` (inline object).\n","oneOf":[{"required":["payment_details_id"],"properties":{"payment_details_id":{"type":"integer","format":"int64","description":"ID of a previously saved payment profile for the end-user"}}},{"required":["payment_details"],"properties":{"payment_details":{"type":"object","required":["payment_method_id","payment_network_id","details"],"properties":{"payment_method_id":{"type":"integer","format":"int64","description":"Payment method ID"},"payment_network_id":{"type":"integer","format":"int64","description":"Payment network ID"},"details":{"type":"object","description":"Payer's account details (fields depend on payment method)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}}}}]}}}}
```

## The PartnerErrorResponse object

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"components":{"schemas":{"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — on-chain transaction relay failed (e.g. simulation reverted)\n- `INSUFFICIENT_BALANCE` — partner wallet lacks tokens to fund escrow\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n","enum":["QUOTE_EXPIRED","QUOTE_NOT_FOUND","QUOTE_ALREADY_USED","PRICE_CHANGED_REQUOTE","ORDER_NOT_FOUND","NO_OFFERS_AVAILABLE","INVALID_REQUEST","INVALID_PAYMENT_DETAILS","RAIL_ROUTE_MISMATCH","UNAUTHORIZED","INTERNAL_ERROR","INVALID_STATUS","TRANSACTOR_ERROR","INSUFFICIENT_BALANCE","OPERATION_NOT_ALLOWED"]},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.unigox.com/api-reference/models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.