# Architecture

![Stacks Blockchain API architecture](/files/jTSvdQ5RK7U39tqM6oPp)

## RPC Endpoints

The `stacks-node` has its own minimal set of http endpoints referred to as `RPC endpoints`.

* The `stacks-blockchain-api` allows clients to access RPC endpoints by proxying requests to a load-balanced pool of `stacks-nodes`.
* For more details on RPC endpoints, see: [RPC Endpoints Documentation](https://github.com/stacks-network/stacks-core/blob/master/docs/rpc-endpoints.md)
* Common RPC endpoints include:
  * `POST /v2/transactions` - Broadcast a transaction
  * `GET /v2/pox` - Retrieve current Proof of Transfer (PoX) relevant information
  * `POST /v2/contracts/call-read/<contract>/<function>` - Evaluate and return the result of calling a Clarity function
  * `POST /v2/fees/transaction` - Evaluate a given transaction and provide transaction fee estimation data
  * `GET /v2/accounts/<address>` - Fetch the current nonce required for creating transactions

## Additional Endpoints

The Stacks Blockchain API implements additional endpoints that provide data unavailable directly from Stacks nodes due to various constraints.

* The `stacks-node` may not persist certain data or may not serve it efficiently to many clients. For instance, while it can return the current STX balance of an account, it cannot provide a history of account transactions.
* The API previously included an embedded Rosetta implementation, but this was removed in favor of the standalone [Stacks Mesh API](/reference/api/stacks-mesh-api.md).
* The API includes support for the Blockchain Naming System (BNS) endpoints.
* For routes, see [`/src/api/routes`](https://github.com/hirosystems/stacks-blockchain-api/tree/master/src/api/routes) in the API repo.

The API creates an "event observer" http server which listens for events from a stacks-node "event emitter".

Events are HTTP POST requests containing:

* Blocks
* Transactions

Byproducts of executed transactions such as:

* Asset transfers
* Smart-contract log data
* Execution cost data

The API processes and stores these events as relational data in PostgreSQL. For the "event observer" code, see [`/src/event-stream`](https://github.com/hirosystems/stacks-blockchain-api/tree/master/src/event-stream) in the API repo.

## OpenAPI and JSON Schema

All http endpoints and responses are defined in OpenAPI and JSON Schema.

* See [`openapi.yaml`](https://github.com/hirosystems/stacks-blockchain-api/blob/master/openapi.yaml) in the API repo
* These are used to auto-generate the docs at <https://docs.stacks.co/reference/api/stacks-blockchain-api>
* JSON Schemas are converted into TypeScript interfaces, which are used internally by the db controller module to transform SQL query results into the correct object shapes.
* OpenAPI and JSON Schemas are also used to generate a standalone `@stacks/blockchain-api-client`.

## Development Setup

To contribute to the [Stacks Blockchain API codebase](https://github.com/hirosystems/stacks-blockchain-api), the easiest way to get started is using the VS Code debugger. It uses docker-compose to set up a stacks-node and Postgres instance.

Alternatively, you can run `npm run dev:integrated` which does the same thing but without a debugger.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacks.co/reference/api/stacks-blockchain-api/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.