{
  "openapi": "3.0.0",
  "info": {
    "title": "InstaPayIPX API",
    "description": "Cross-rail payment orchestration API for instant settlements across XRPL, Xahau, Solana, FedNow, and RTP networks.",
    "version": "1.0.0",
    "contact": {
      "name": "InstaPayIPX Support",
      "url": "https://instapayipx.com"
    }
  },
  "servers": [
    {
      "url": "https://www.instapayipx.com/api/v1",
      "description": "Production server"
    },
    {
      "url": "https://www.instapayipx.com/api/v1",
      "description": "Test server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ipx_<API_KEY>"
      }
    },
    "schemas": {
      "PayoutRequest": {
        "type": "object",
        "required": ["rail", "destination", "amount", "currency"],
        "properties": {
          "rail": {
            "type": "string",
            "enum": ["xrpl", "xahau", "solana", "fednow", "rtp"],
            "description": "Payment rail to use"
          },
          "destination": {
            "type": "string",
            "description": "Destination address or account number"
          },
          "amount": {
            "type": "string",
            "description": "Amount to send (e.g., '10.00')"
          },
          "currency": {
            "type": "string",
            "description": "Currency code (e.g., 'XRP', 'USD', 'USDC')"
          },
          "memo": {
            "type": "string",
            "description": "Optional memo or reference"
          },
          "idempotency_key": {
            "type": "string",
            "description": "Unique key to prevent duplicate payouts"
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": ["amount", "chain"],
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount to quote"
          },
          "chain": {
            "type": "string",
            "enum": ["xrpl", "xahau", "solana", "fednow", "rtp"],
            "description": "Blockchain or rail network"
          },
          "currency": {
            "type": "string",
            "description": "Currency code (default: USD)"
          },
          "asset": {
            "type": "string",
            "description": "Specific asset identifier"
          }
        }
      },
      "PayoutResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique payout ID"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "succeeded", "failed"],
            "description": "Current payout status"
          },
          "rail": {
            "type": "string",
            "description": "Payment rail used"
          },
          "destination": {
            "type": "string",
            "description": "Destination address"
          },
          "amount": {
            "type": "string",
            "description": "Amount sent"
          },
          "currency": {
            "type": "string",
            "description": "Currency sent"
          },
          "transaction_hash": {
            "type": "string",
            "description": "Blockchain transaction hash"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number",
            "description": "Original amount"
          },
          "converted_amount": {
            "type": "number",
            "description": "Converted amount"
          },
          "currency": {
            "type": "string",
            "description": "Source currency"
          },
          "target_currency": {
            "type": "string",
            "description": "Target currency"
          },
          "rate": {
            "type": "number",
            "description": "Exchange rate"
          },
          "fee": {
            "type": "number",
            "description": "Network fee"
          },
          "total": {
            "type": "number",
            "description": "Total amount including fees"
          },
          "rail": {
            "type": "string",
            "description": "Recommended rail"
          },
          "estimated_time": {
            "type": "string",
            "description": "Estimated settlement time"
          }
        }
      },
      "Rail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Rail identifier"
          },
          "name": {
            "type": "string",
            "description": "Rail display name"
          },
          "type": {
            "type": "string",
            "description": "Rail type (blockchain, real-time, etc.)"
          },
          "currencies": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Supported currencies"
          },
          "status": {
            "type": "string",
            "enum": ["active", "maintenance", "inactive"],
            "description": "Current rail status"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "details": {
            "type": "string",
            "description": "Additional error details"
          },
          "code": {
            "type": "string",
            "description": "Error code"
          }
        }
      }
    }
  },
  "paths": {
    "/rails": {
      "get": {
        "summary": "Get available payment rails",
        "description": "Returns a list of available payment rails and their current status",
        "operationId": "getRails",
        "tags": ["Rails"],
        "responses": {
          "200": {
            "description": "List of available rails",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rails": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Rail"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payout": {
      "post": {
        "summary": "Create a payout",
        "description": "Initiate a payout across any supported payment rail",
        "operationId": "createPayout",
        "tags": ["Payouts"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayoutRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payout created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayoutResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/quote": {
      "post": {
        "summary": "Get a quote",
        "description": "Get a quote for a cross-rail payment including fees and exchange rates",
        "operationId": "getQuote",
        "tags": ["Quotes"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/transactions": {
      "get": {
        "summary": "List transactions",
        "description": "Get a list of transactions for the authenticated account",
        "operationId": "listTransactions",
        "tags": ["Transactions"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (max: 100)",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by transaction status",
            "schema": {
              "type": "string",
              "enum": ["pending", "processing", "succeeded", "failed"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of transactions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transactions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PayoutResponse"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/balance": {
      "get": {
        "summary": "Get balance",
        "description": "Get balance for a specific address or the default account",
        "operationId": "getBalance",
        "tags": ["Balance"],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "description": "Address to check balance for",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Balance information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": {
                      "type": "string"
                    },
                    "balances": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "currency": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Rails",
      "description": "Payment rail operations"
    },
    {
      "name": "Payouts",
      "description": "Payout creation and management"
    },
    {
      "name": "Quotes",
      "description": "Payment quotes and estimates"
    },
    {
      "name": "Transactions",
      "description": "Transaction history and status"
    },
    {
      "name": "Balance",
      "description": "Account balance queries"
    }
  ]
}