KV FastData API

Read-only JSON API for NEAR FastData key-value storage

All POST endpoints accept a JSON body and return JSON. Base URL: https://kv.main.fastnear.com

GET Endpoints

GET /v0/latest/{current_account_id}/{predecessor_id}/{key}

Get the latest value of a specific key.

curl https://kv.main.fastnear.com/v0/latest/app.near/alice.near/score

GET /v0/history/{current_account_id}/{predecessor_id}/{key}

Get the full history of a specific key.

curl https://kv.main.fastnear.com/v0/history/app.near/alice.near/score

POST Endpoints

Common Body Fields (all POST endpoints)

POST /v0/all/{predecessor_id}

Get latest values of all keys across all contracts for a predecessor. Must be paginated.

curl -X POST https://kv.main.fastnear.com/v0/all/alice.near \
  -H "Content-Type: application/json" \
  -d '{"limit":50}'

POST /v0/history/{current_account_id}/{predecessor_id}

Full history of KV writes by a predecessor to a contract.

curl -X POST https://kv.main.fastnear.com/v0/history/app.near/alice.near \
  -H "Content-Type: application/json" \
  -d '{"key_prefix":"settings/"}'

POST /v0/latest/{current_account_id}/{predecessor_id}

Latest values by predecessor + contract. Same body fields.

curl -X POST https://kv.main.fastnear.com/v0/latest/app.near/alice.near \
  -H "Content-Type: application/json" \
  -d '{"key_prefix":"settings/"}'

POST /v0/history/{current_account_id}

Full history of all KV writes to a contract (all predecessors). Same body fields.

curl -X POST https://kv.main.fastnear.com/v0/history/app.near \
  -H "Content-Type: application/json" \
  -d '{"key":"score","limit":10}'

POST /v0/latest/{current_account_id}

Latest values for a contract (all predecessors). Same body fields.

POST /v0/history

Global lookup: all writes to a key across all accounts.

curl -X POST https://kv.main.fastnear.com/v0/history \
  -H "Content-Type: application/json" \
  -d '{"key":"score","limit":10}'

POST /v0/multi

Batch lookup: latest value for multiple keys (max 100).

curl -X POST https://kv.main.fastnear.com/v0/multi \
  -H "Content-Type: application/json" \
  -d '{"keys":["app.near/alice.near/score","app.near/bob.near/score"]}'

Response Format

Default response (include_metadata=false)

{
  "entries": [
    {
      "predecessor_id": "alice.near",
      "current_account_id": "app.near",
      "block_height": 123456789,
      "block_timestamp": 1700000000000,
      "key": "score",
      "value": 1500
    }
  ],
  "page_token": "eyJr..."
}

With metadata (include_metadata=true)

{
  "entries": [
    {
      "receipt_id": "Aw1MHvj3GHBon1GBiGMWqafBJCBMqXTPw4PoSaSEjnkQ",
      "action_index": 0,
      "tx_hash": "6i9brQEJzLqmLLoqCcPPQih7YeYmLZcLxjW8zGnx3LFh",
      "signer_id": "alice.near",
      "predecessor_id": "alice.near",
      "current_account_id": "app.near",
      "block_height": 123456789,
      "block_timestamp": 1700000000000,
      "key": "score",
      "value": 1500
    }
  ]
}

Multi response

{
  "entries": [
    {"predecessor_id": "alice.near", "current_account_id": "app.near", "key": "score", "value": 1500, ...},
    null
  ]
}

Entries match input keys order. null = key not found.

Pagination

1. Send your request (optionally with limit).
2. If the response includes page_token, resend same request with that token.
3. Repeat until page_token is absent.

Errors

Error body: {"error": "description"}

Writing Data

Data is written by sending a NEAR transaction. Call the method __fastdata_kv on any account, passing a JSON object as the argument. The root-level keys of the JSON become your KV keys, and the values are stored as-is.

How it works

• Your account (predecessor_id) calls __fastdata_kv on a target account (current_account_id)
• The JSON argument's root keys become the stored keys
• Values can be any valid JSON: strings, numbers, objects, arrays, booleans, null
• Multiple keys can be written in a single call (max 256 keys)
• Max key length: 1,024 bytes. Max value size: 256 KB (serialized)

Example: Store a single value

near call my-app.near __fastdata_kv '{"score": 1500}' --accountId alice.near

This stores key score with value 1500, readable at:

GET https://kv.main.fastnear.com/v0/latest/my-app.near/alice.near/score

Example: Store multiple keys at once

near call my-app.near __fastdata_kv '{
  "settings/lang": "en",
  "settings/volume": 80,
  "profile": {"name": "Alice", "level": 42}
}' --accountId alice.near

This stores three keys in one transaction. Query all settings with a prefix filter:

curl -X POST https://kv.main.fastnear.com/v0/latest/my-app.near/alice.near \
  -H "Content-Type: application/json" \
  -d '{"key_prefix":"settings/"}'

Example: Use any account as a namespace

near call data-store.alice.near __fastdata_kv '{"hello": "world"}' --accountId alice.near

The account data-store.alice.near doesn't need to exist. It acts purely as a namespace for organizing your data.

Machine-readable API reference (skill.md)