# Public APIs

GorillaPool maintains a public `1sat-server` Basic usage is documented below. See the auto-generated [swagger documentation](https://ordinals.gorillapool.io/api/docs/) for a complete API reference.

The API is also [available on Github](https://github.com/shruggr/1sat-server).

### Other APIs

* There is also basic support from [#whats-on-chain](#whats-on-chain "mention")
* The [#bmap-api](#bmap-api "mention") can be used to resolve inscriptions with support for several other data protocols. 

## 1SAT Server Endpoints

### Get Files, Inscriptions

```
METHOD: GET
```

Get inscription file for a given origin. 

```
https://ordinals.gorillapool.io/api/files/inscriptions/:origin
```

Sample response

<figure><img src="https://243402672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FszFH9JXtqC2V7WUpj8IT%2Fuploads%2FsYeZXGwixnYQQMvwk6PR%2Fimage.png?alt=media&#x26;token=4a33c686-973d-4d1d-980b-156f329b09cb" alt=""><figcaption></figcaption></figure>

### Get Inscriptions

```
Method: GET
```

Get inscription data for a given origin.

```
https://ordinals.gorillapool.io/api/inscriptions/origin/:origin
```

Get inscriptions for a given txid.

```
https://ordinals.gorillapool.io/api/inscriptions/txid/:txid
```

Sample response

```json
[
    {
      // inscription number
      "id": 165, 
      // transaction id
      "txid": "e17d7856c375640427943395d2341b6ed75f73afc8b22bb3681987278978a584",
      // output index
      "vout": 1,
      // file info
      "file": {
        "hash": "3dbe16ec7625e0d8a02ceaa5b2b03bc412c06186d03fbd69090c162469cf0292",
        "size": 2592,
        "type": "image/png"
      },
      // 1sat output origin
      "origin": "e17d7856c375640427943395d2341b6ed75f73afc8b22bb3681987278978a584_1",
      // ordinal number
      "ordinal": 0,
      // block height
      "height": 783968,
      // block index
      "idx": 756,
      // hash of locking script preceding inscription
      "lock": "5d5c07f532ae28f90263209aeba5417366569c60947b74b363ce55c5d57d253d"
    }
]
```

### Get Ordinal Utxos

```
Method: GET
```

Because ordinals exist in Bitcoin Script, . Get unspent utxos with ordinal locks matching a given address.

```
https://ordinals.gorillapool.io/api/utxos/address/:address
```

Sample response

{% code overflow="wrap" %}

```json
[
    {
      "txid": "5af82e9c72688270afc9c70a3f523560600d1aa2c39eab74756d11243f4752ba",
      "vout": 0,
      "satoshis": 1,
      "lock": "b0a542a4a4707f7b5b48f4c7a45e12bee4f9481a5ad3db250dfd3730f5ff4225",
      "origin": "5af82e9c72688270afc9c70a3f523560600d1aa2c39eab74756d11243f4752ba_0",
      "ordinal": 0
    },
    {
      "txid": "7ecb6b642cf7e44cf757562fe88f8c51f0bb844e41c6c844eca2b13af8c49ca0",
      "vout": 0,
      "satoshis": 1,
      "lock": "b0a542a4a4707f7b5b48f4c7a45e12bee4f9481a5ad3db250dfd3730f5ff4225",
      "origin": "7ecb6b642cf7e44cf757562fe88f8c51f0bb844e41c6c844eca2b13af8c49ca0_0",
      "ordinal": 0
    }
]
```

{% endcode %}

You can also get inscriptions for UTXOs in a single request

```
https://ordinals.gorillapool.io/api/utxos/address/:address/inscriptions
```

## Get Lock Utxos

```
Method: GET
```

Get unspent outputs for a given "lock", which is the scripthash of the locking script up to the point of an inscription.

```
https://ordinals.gorillapool.io/api/utxos/lock/:lock
```

Returns UTXOs:

```json
[{
    "txid": string,
    "vout": number,
    "satoshis": number,
    "lock": string,
    "spend": string,
    "origin": string,
    "ordinal": number,
}]
```

## Address Events - SSE

SSE endpoints are available for real-time mempool tx notifications. Watch multiple addresses or locking script hashes simultaneously, and get notified when a transaction occurs matching. Add query param `address` for each address you want to monitor, and `lock` for each script hash.

You will receive both new Inscription UTXOs AND spends from the same messages. If the `spend` field is not `null`, that means you have received a spend, and you should remove the UTXO identified by `txid`:`vout` from your UTXO set.

If the spend field is `null`, then this is a new Inscription in your wallet.

{% code overflow="wrap" %}

```javascript
https://ordinals.gorillapool.io/api/subscribe?address=:address1&address=:address2&lock=:lock1&...
```

{% endcode %}

Listening for ordinal address activity:

```tsx
const API_HOST = "https://ordinals.gorillapool.io/api/"
const s = new EventSource(`${API_HOST}subscribe?address=${ordAddress}`);

s.onmessage = (e) => {
    console.log({ message: e })
}
// s.onopen
// s.onerror
```

## What's On Chain

WhatsOnChain.com also provides 1Sat Ordinals support by tagging the inscriptions and providing a plugin for rending ordinals by txid and outpout index as follows:

{% code overflow="wrap" %}

```
https://plugins.whatsonchain.com/api/plugin/main/:txid/:vout
```

{% endcode %}

## BMAP API

Get a BMAP Transaction object as a formatted JSON string

```
https://b.map.sv/tx/:txid
```

or non-formatted bmap

```
https://b.map.sv/tx/:txid/bmap
```

raw transaction hex

```
https://b.map.sv/tx/:txid/raw
```

or BOB format

```
https://b.map.sv/tx/:txid/bob
```


---

# 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.1satordinals.com/public-apis.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.