Public API

View Markdown (opens in a new tab)

Use the read-only floored v1 API to add indexed Ethscriptions and floored data to your own application.

Open interactive API documentation

Make your first request

You need a verified Premium or Admin account to create and use a developer key.

1. Verify your wallet in floored.
2. Open Settings.
3. Find Developer and API keys.
4. Enter a descriptive name and choose Create key.
5. Copy the raw key before choosing Done. It appears only once.
6. Send the key in the X-API-Key header.

curl "https://api.floored.app/v1/ethscriptions?limit=20&sort=newest" \
  -H "X-API-Key: flr_sk_your_key"

The key starts with flr_sk_. floored stores a one-way digest and safe display information, not another copy of the raw value. Revoking a key is permanent.

Eligible accounts can create several keys, but quotas and rate limits apply to the owner across all keys.

URLs and interactive reference

• Base URL: https://api.floored.app/v1
• Interactive documentation: https://data.floored.app/gfy/docs
• OpenAPI JSON: https://data.floored.app/gfy/openapi.json

GET /v1/health does not require a key. Production data endpoints require X-API-Key.

Use the OpenAPI document for the current operation list, parameters, and schemas.

Choose a resource

v1 provides read operations for:

• Ethscriptions, existence checks, batches, ownership verification, comments, and activity
• Account Ethscriptions, collections, profile-topic comments, and activity
• Collection directory, details, items, traits, holders, statistics, and activity
• Ownership-verified marketplace listings and auctions
• Marketplace catalog
• Public search
• Global activity feed

Account comments are comments whose topic is the account profile. v1 does not provide a query for every comment authored by an address or for comment replies.

Read a response

A single resource uses data:

{
  "data": {}
}

A list also includes pagination:

{
  "data": [],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "opaque-cursor"
  }
}

Health is the one envelope exception. It returns status, version, and timestamp directly.

Paginate results

Chronological streams use opaque cursor pagination with limit and cursor. Directories, rankings, and current projections use limit and offset.

The default limit is 50 and the maximum is 100 unless an operation's schema says otherwise. Pass nextCursor back exactly as returned. Do not parse or construct cursor values.

Handle identifiers and numbers

• Ethereum addresses and hashes are lowercase 0x strings.
• Large blockchain integers are decimal strings.
• Wei fields are decimal strings with names such as priceWei.
• API and database timestamps use ISO 8601 UTC.
• Date-only statistics use YYYY-MM-DD.

Handle errors

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 100",
    "requestId": "request-id",
    "details": {}
  }
}

Stable codes include invalid_request, invalid_api_key, insufficient_scope, not_found, rate_limit_exceeded, internal_error, and service_unavailable.

Response	What to do
401 or invalid_api_key	Send the raw key in X-API-Key. Check whether the key was revoked, suspended, or belongs to an account that is no longer eligible.
403 or insufficient_scope	Use a key with the scope required by the operation.
429 or rate_limit_exceeded	Stop retrying and wait for the rate-limit window. Creating or rotating keys does not increase the owner's quota.

Keep the requestId when reporting an API problem.

Account for data freshness

The API reads indexed protocol and application data. A confirmed Ethereum transaction may appear later in collection details, activity, comments, listings, auctions, statistics, or search.

Active listing and auction results are returned only after supported-contract and ownership checks. Do not describe v1 results as direct, real-time Ethereum RPC reads.

Review key usage

Settings shows 30 UTC days of requests, errors, rate-limited requests, last use, and average response time for each key. Recent usage can take a short time to appear.

v1 limits

v1 does not provide:

• Public write operations
• Real-time subscriptions
• Administrative indexer controls
• Personalized wallet results
• Compatibility guarantees for internal /gfy response formats

For complete parameters and schemas, use the interactive API documentation.