Genesis Arbitrage

Genesis Arbitrage · · 3 min read

OpenAPI

OpenAPI (the OpenAPI Specification, OAS) is the open standard for describing an HTTP API in a machine-readable way: which paths and methods a service has, what parameters they take, what they return and how to pass a key. The document is written in JSON or YAML, and both people and programs can understand the API from it without access to the source code.

Where the standard came from

The standard grew out of the Swagger Specification, first released in 2011. In 2015 Swagger 2.0 was donated to the OpenAPI Initiative, an open project of the Linux Foundation, and since 2016 the specification has been developed as OpenAPI. Version 3.0 came out in 2017 and 3.1 in February 2021; the newest line is 3.2 (the 3.1 specification).

What the document describes

A shortened excerpt of the Genesis API spec, the funding rates operation and the key scheme:

{
  "openapi": "3.1.0",
  "servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
  "paths": {
    "/funding/rates": {
      "get": {
        "operationId": "getFundingRates",
        "summary": "Funding rates",
        "x-genesis-plans": ["trial", "start", "pro", "max"],
        "parameters": [
          { "name": "coin", "in": "query", "required": false,
            "schema": { "type": "string" } }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header",
                      "name": "X-API-Key" }
    }
  }
}

Fields prefixed with x- are specification extensions: x-genesis-plans lists the plans that include the operation.

What a spec is for

Among its uses the standard lists generating documentation, generating clients and servers in different languages, and testing. For AI agents a spec is a ready-made toolset: an operation with an operationId, a description and a parameter schema maps onto a tool for function calling or an MCP server.

OpenAPI in Genesis API

The Genesis API spec lives at genesisarbitrage.com/openapi.json: OpenAPI 3.1, 37 operations, the key in the X-API-Key header (authentication). It can also be found automatically: the /.well-known/api-catalog file on genesisarbitrage.com, defined by RFC 9727, points to it with a service-desc link. How to connect the spec to an agent is covered in Genesis API for AI agents.

See also: REST API, JSON, API endpoint, crypto market data for AI agents.

Questions and answers

Are Swagger and OpenAPI the same thing?

They are one standard under two names: the Swagger Specification has been developed as OpenAPI since 2016. Version 2.0 was still released as Swagger 2.0, and from 3.0 on it is published as the OpenAPI Specification.

Do I need an SDK if there is a spec?

Not for Genesis API: every request is a GET with one header, so any HTTP client works. Generating a client from the spec makes sense if you want typed methods.