{
  "openapi": "3.1.0",
  "info": {
    "title": "FinLinks Developer Platform",
    "version": "v1",
    "description": "Public snapshot of the FinLinks Developer Platform HTTP API. This document is version v1, taken from source snapshot e660fb1595af6606956bad31b202c6ae20803e8d. Test-mode API keys (`fl_test_`) are reserved and disabled. Use the Public API (API key) section for live invoice, balance, and ledger calls. The Merchant session API section documents Portal-authenticated key and webhook management routes; those routes require a merchant Portal session, not an API key."
  },
  "servers": [
    {
      "url": "https://finlinks-circle-service.onrender.com",
      "description": "Production API base used by the FinLinks Portal Developer Platform"
    }
  ],
  "tags": [
    {
      "name": "Public API (API key)",
      "description": "Live Base mainnet invoices, balances, and ledger activity. Authenticate with a live developer API key (`Authorization: Bearer fl_live_…`)."
    },
    {
      "name": "Merchant session API (Portal JWT)",
      "description": "Merchant Portal session routes for API keys and webhook endpoints. Authenticate with the merchant access session, not an API key. These routes are not called with `fl_live_` keys."
    }
  ],
  "paths": {
    "/v1/invoices": {
      "post": {
        "operationId": "createInvoice",
        "summary": "Create an invoice",
        "tags": [
          "Public API (API key)"
        ],
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "schema": {
                  "type": "string"
                },
                "description": "Relative URL for the created invoice."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-finlinks-scope": "invoices:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceCreate"
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "description": "Replays the committed response for the same merchant and key for 24 hours. A changed normalized payload returns 409."
      },
      "get": {
        "operationId": "listInvoices",
        "summary": "List mainnet invoices",
        "tags": [
          "Public API (API key)"
        ],
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "items",
                        "nextCursor"
                      ],
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Invoice"
                          }
                        },
                        "nextCursor": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-finlinks-scope": "invoices:read",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "PENDING",
                "PARTIAL",
                "PAID",
                "OVERPAID",
                "UNDERPAID",
                "EXPIRED",
                "CANCELLED",
                "REFUND_PENDING",
                "REFUNDED"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ]
      }
    },
    "/v1/invoices/{id}": {
      "get": {
        "operationId": "getInvoice",
        "summary": "Read a mainnet invoice",
        "tags": [
          "Public API (API key)"
        ],
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/InvoiceDetail"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-finlinks-scope": "invoices:read",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ]
      }
    },
    "/v1/balances": {
      "get": {
        "operationId": "getBalances",
        "summary": "Read Base USDC balances",
        "tags": [
          "Public API (API key)"
        ],
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Balance"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-finlinks-scope": "balances:read"
      }
    },
    "/v1/ledger": {
      "get": {
        "operationId": "getLedger",
        "summary": "List merchant ledger activity",
        "tags": [
          "Public API (API key)"
        ],
        "security": [
          {
            "developerKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/LedgerPage"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-finlinks-scope": "ledger:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "INBOUND",
                "OUTBOUND"
              ]
            }
          },
          {
            "name": "startDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ]
      }
    },
    "/merchant/developers/keys": {
      "post": {
        "operationId": "createDeveloperKey",
        "summary": "Create a live key",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/KeyCreated"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KeyInput"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listDeveloperKeys",
        "summary": "List key metadata",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "items"
                      ],
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/KeyMetadata"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/merchant/developers/keys/{id}/roll": {
      "post": {
        "operationId": "rollDeveloperKey",
        "summary": "Roll a live key",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/KeyRolled"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RollKeyInput"
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ]
      }
    },
    "/merchant/developers/keys/{id}/revoke": {
      "post": {
        "operationId": "revokeDeveloperKey",
        "summary": "Revoke a live key",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "204": {
            "description": "Completed",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ]
      }
    },
    "/merchant/developers/webhooks/endpoints": {
      "post": {
        "operationId": "createDeveloperWebhookEndpoint",
        "summary": "Register an endpoint",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/EndpointCreated"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EndpointInput"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listDeveloperWebhookEndpoints",
        "summary": "List endpoints",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "items",
                        "nextCursor"
                      ],
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Endpoint"
                          }
                        },
                        "nextCursor": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ]
      }
    },
    "/merchant/developers/webhooks/endpoints/{id}/disable": {
      "post": {
        "operationId": "disableDeveloperWebhookEndpoint",
        "summary": "Disable an endpoint",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "204": {
            "description": "Completed",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ]
      }
    },
    "/merchant/developers/webhooks/test": {
      "post": {
        "operationId": "testDeveloperWebhook",
        "summary": "Send a signed test event",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/WebhookTestResult"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookTestInput"
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/merchant/developers/webhooks/deliveries": {
      "get": {
        "operationId": "listDeveloperWebhookDeliveries",
        "summary": "List deliveries from the last seven days",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "items",
                        "nextCursor"
                      ],
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Delivery"
                          }
                        },
                        "nextCursor": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "parameters": [
          {
            "name": "endpointId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ]
      }
    },
    "/merchant/developers/webhooks/deliveries/{id}/replay": {
      "post": {
        "operationId": "replayDeveloperWebhook",
        "summary": "Queue a failed delivery replay",
        "tags": [
          "Merchant session API (Portal JWT)"
        ],
        "security": [
          {
            "merchantSession": []
          }
        ],
        "responses": {
          "202": {
            "description": "Queued",
            "headers": {
              "X-FinLinks-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "data"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "deliveryId"
                      ],
                      "properties": {
                        "deliveryId": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    }
  },
  "webhooks": {
    "developerEvent": {
      "post": {
        "operationId": "receiveDeveloperWebhook",
        "summary": "Receive a signed developer event",
        "security": [],
        "parameters": [
          {
            "name": "X-FinLinks-Webhook-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-FinLinks-Webhook-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-FinLinks-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-FinLinks-Delivery-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receiver accepted the event."
          },
          "default": {
            "description": "Receiver rejected the event."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "developerKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Live developer API key beginning with fl_live_."
      },
      "merchantSession": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Existing merchant access session."
      }
    },
    "headers": {
      "RequestId": {
        "description": "Unique identifier generated for this response.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "parameters": {
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[!-~]{1,128}$"
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Structured error. Rate limits and in-progress idempotency conflicts also return Retry-After.",
        "headers": {
          "X-FinLinks-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "success",
          "code",
          "error"
        ],
        "properties": {
          "success": {
            "const": false
          },
          "code": {
            "type": "string",
            "examples": [
              "DEVELOPER_KEY_INVALID",
              "DEVELOPER_SCOPE_REQUIRED",
              "IDEMPOTENCY_KEY_REUSED"
            ]
          },
          "error": {
            "type": "object",
            "required": [
              "message"
            ],
            "properties": {
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "next": {
                "type": "string"
              }
            }
          }
        }
      },
      "InvoiceCreate": {
        "type": "object",
        "required": [
          "invoiceNumber",
          "title",
          "amount",
          "expiresAt"
        ],
        "properties": {
          "invoiceNumber": {
            "type": "string",
            "maxLength": 64
          },
          "title": {
            "type": "string",
            "maxLength": 255
          },
          "amount": {
            "type": "string",
            "pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,6})?$",
            "examples": [
              "10.500000"
            ],
            "description": "Positive Base USDC string. Up to six fractional digits."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "description": {
            "type": "string",
            "maxLength": 8000
          },
          "tradeType": {
            "type": "string",
            "enum": [
              "GOODS",
              "SERVICE",
              "B2C"
            ],
            "default": "SERVICE"
          },
          "tradeRef": {
            "type": "string",
            "maxLength": 128
          }
        },
        "additionalProperties": false
      },
      "Invoice": {
        "type": "object",
        "required": [
          "id",
          "invoiceNumber",
          "title",
          "status",
          "amount",
          "payAmount",
          "paidAmount",
          "tokenSymbol",
          "blockchain",
          "createdAt",
          "expiresAt",
          "paidAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "invoiceNumber": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "PARTIAL",
              "PAID",
              "OVERPAID",
              "UNDERPAID",
              "EXPIRED",
              "CANCELLED",
              "REFUND_PENDING",
              "REFUNDED"
            ]
          },
          "amount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "payAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "paidAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "tokenSymbol": {
            "type": "string"
          },
          "blockchain": {
            "type": "string",
            "enum": [
              "BASE"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "paidAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "InvoiceDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Invoice"
          },
          {
            "type": "object",
            "required": [
              "checkoutUrl"
            ],
            "properties": {
              "checkoutUrl": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "uri"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        ]
      },
      "Balance": {
        "type": "object",
        "required": [
          "asset",
          "blockchain",
          "walletProvisioned",
          "onChainAmount",
          "availableAmount",
          "heldAmount",
          "asOf"
        ],
        "properties": {
          "asset": {
            "type": "string",
            "enum": [
              "USDC"
            ]
          },
          "blockchain": {
            "type": "string",
            "enum": [
              "BASE"
            ]
          },
          "walletProvisioned": {
            "type": "boolean"
          },
          "onChainAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "availableAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "heldAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "asOf": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LedgerEntry": {
        "type": "object",
        "required": [
          "id",
          "direction",
          "businessType",
          "status",
          "amount",
          "feeAmount",
          "netAmount",
          "tokenSymbol",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "INBOUND",
              "OUTBOUND"
            ]
          },
          "businessType": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "amount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "feeAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "netAmount": {
            "type": "string",
            "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
            "examples": [
              "0.000001",
              "10.500000"
            ]
          },
          "tokenSymbol": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LedgerPage": {
        "type": "object",
        "required": [
          "items",
          "page",
          "limit",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LedgerEntry"
            }
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1
          },
          "total": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "KeyInput": {
        "type": "object",
        "required": [
          "name",
          "environment",
          "scopes"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "environment": {
            "type": "string",
            "enum": [
              "live"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "invoices:read",
                "invoices:write",
                "balances:read",
                "ledger:read"
              ]
            },
            "minItems": 1,
            "maxItems": 4
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "KeyMetadata": {
        "type": "object",
        "required": [
          "id",
          "name",
          "maskedPrefix",
          "environment",
          "scopes",
          "status",
          "createdAt",
          "lastUsedAt",
          "expiresAt",
          "revokedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "maskedPrefix": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "live"
            ]
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "invoices:read",
                "invoices:write",
                "balances:read",
                "ledger:read"
              ]
            },
            "minItems": 1,
            "maxItems": 4
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "expired",
              "revoked"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "expiresAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "revokedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "KeyCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/KeyMetadata"
          },
          {
            "type": "object",
            "required": [
              "apiKey"
            ],
            "properties": {
              "apiKey": {
                "type": "string",
                "pattern": "^fl_live_[A-Za-z0-9_-]{43}$",
                "description": "Only returned once. Store it securely."
              }
            }
          }
        ]
      },
      "RollKeyInput": {
        "type": "object",
        "required": [],
        "properties": {
          "graceHours": {
            "type": "integer",
            "enum": [
              0,
              24
            ],
            "default": 24
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "KeyRolled": {
        "allOf": [
          {
            "$ref": "#/components/schemas/KeyCreated"
          },
          {
            "type": "object",
            "required": [
              "previousExpiresAt"
            ],
            "properties": {
              "previousExpiresAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "EndpointInput": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "Public HTTPS endpoint, up to 20 active endpoints per merchant."
          }
        },
        "additionalProperties": false
      },
      "Endpoint": {
        "type": "object",
        "required": [
          "id",
          "url",
          "createdAt",
          "disabledAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "disabledAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "EndpointCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Endpoint"
          },
          {
            "type": "object",
            "required": [
              "signingSecret"
            ],
            "properties": {
              "signingSecret": {
                "type": "string",
                "description": "Only returned once."
              }
            }
          }
        ]
      },
      "WebhookTestInput": {
        "type": "object",
        "required": [
          "endpointId"
        ],
        "properties": {
          "endpointId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "WebhookTestResult": {
        "type": "object",
        "required": [
          "deliveryId",
          "delivered",
          "responseStatus",
          "latencyMs",
          "failureCode"
        ],
        "properties": {
          "deliveryId": {
            "type": "string",
            "format": "uuid"
          },
          "delivered": {
            "type": "boolean"
          },
          "responseStatus": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 100,
                "maximum": 599
              },
              {
                "type": "null"
              }
            ]
          },
          "latencyMs": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "failureCode": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Delivery": {
        "type": "object",
        "required": [
          "id",
          "endpointId",
          "eventId",
          "eventType",
          "requestHeaders",
          "requestBody",
          "responseStatus",
          "responseBody",
          "responseTruncated",
          "latencyMs",
          "attemptCount",
          "status",
          "failureCode",
          "replayOfId",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "endpointId": {
            "type": "string",
            "format": "uuid"
          },
          "eventId": {
            "type": "string",
            "format": "uuid"
          },
          "eventType": {
            "type": "string",
            "enum": [
              "webhook.test",
              "invoice.paid",
              "invoice.underpaid",
              "invoice.expired",
              "invoice.cancelled"
            ]
          },
          "requestHeaders": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "requestBody": {
            "type": "string",
            "description": "Frozen UTF-8 JSON body."
          },
          "responseStatus": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 100,
                "maximum": 599
              },
              {
                "type": "null"
              }
            ]
          },
          "responseBody": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "responseTruncated": {
            "type": "boolean"
          },
          "latencyMs": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "attemptCount": {
            "type": "integer",
            "minimum": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "sending",
              "succeeded",
              "failed"
            ]
          },
          "failureCode": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "replayOfId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "livemode",
          "createdAt",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "webhook.test",
              "invoice.paid",
              "invoice.underpaid",
              "invoice.expired",
              "invoice.cancelled"
            ]
          },
          "livemode": {
            "const": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "endpointId"
                ],
                "properties": {
                  "endpointId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "invoiceId",
                  "amount",
                  "paidAmount",
                  "tokenSymbol"
                ],
                "properties": {
                  "invoiceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amount": {
                    "type": "string",
                    "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
                    "examples": [
                      "0.000001",
                      "10.500000"
                    ]
                  },
                  "paidAmount": {
                    "type": "string",
                    "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$",
                    "examples": [
                      "0.000001",
                      "10.500000"
                    ]
                  },
                  "tokenSymbol": {
                    "type": "string"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}
