# API Definition

{% hint style="info" %}
All the JS examples in this definition are made using [PaltaLabs' Mercury SDK](https://github.com/paltalabs/mercury-sdk). We thank the Paltalabs team for providing and maintaining this SDK!

Before you use those examples, you need to define `mercuryInstance`:

```javascript
import { Mercury } from "mercury-sdk";

const mercuryInstance = new Mercury({
  backendEndpoint: process.env.MERCURY_BACKEND_ENDPOINT,
  graphqlEndpoint: process.env.MERCURY_GRAPHQL_ENDPOINT,
  email: process.env.MERCURY_TESTER_EMAIL,
  password: process.env.MERCURY_TESTER_PASSWORD,
});
```

{% endhint %}

### Contract Events Subscription

Contract event subscriptions allow you to start indexing smart contract events.

{% tabs %}
{% tab title="cURL" %}

```
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "contract_id": "CONTRACT_ID",
          "topic1": "SOME_SCVAL_XDR",
          "topic2": "SOME_SCVAL_XDR",
          "topic3": "SOME_SCVAL_XDR",
          "topic4": "SOME_SCVAL_XDR"
         }' \
     http://172.232.157.194:3030/event
```

{% endtab %}

{% tab title="Javascript (Mercury SDK From PaltaLabs)" %}

```javascript
mercuryInstance.subscribeToContractEvents({
  contractId: "CONTRACT_ID",
  topic1: "SOME_SCVAL_XDR",
  topic2: "SOME_SCVAL_XDR",
  topic3: "SOME_SCVAL_XDR",
  topic4: "SOME_SCVAL_XDR",
});
```

{% endtab %}
{% endtabs %}

### Contract Data Ledger Entries Subscription

Contract data ledger entries subscriptions allow you to index all changes to certain contract data. For example, imagine that it could keep track of balances.

{% tabs %}
{% tab title="cURL" %}

```
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "contract_id": "CONTRACT_ID",
          "key_xdr": "SOME_SCVAL_XDR",
          "durability": "persistent"
          "hydrate": true
         }' \
     http://172.232.157.194:3030/entry
```

{% endtab %}

{% tab title="Javascript (Mercury SDK From PaltaLabs)" %}

```javascript
const args = {
    contractId: "CONTRACT_ID",
    keyXdr: "SOME_SCVAL_XDR", // For example AAAAFA== is contract instance.
    durability: "persistent",
    hydrate: true,
}
const subscribe = await mercuryInstance.subscribeToLedgerEntries(args).catch((err) => {
    console.error(err)
})
```

{% endtab %}
{% endtabs %}

Note that the hydrate: bool flag specifies whether you want to make a light upon subscribing. This means the current value in the ledger will be queriable after the subscription.

### Ledger Entries Expiration Subscription

Tracks the current lifetime of a certain ledger entry. 

{% tabs %}
{% tab title="cURL" %}

```
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "hash_xdr": "HASHED_LEDGER_KEY_XDR_BASE64",
         }' \
     http://172.232.157.194:3030/expiration
```

{% endtab %}
{% endtabs %}

Where `hash_xdr` is a base64 encoded XDR object `Hash` which wraps the SHA256 of a `LedgerKey` XDR object. 

Generating the correct `hash_xdr` can be non-trivial without guidance, so we will include here a brief Rust snippet that you can use to calculate the param:

```rust
// Make sure to import sha2::{Digest, Sha256} and all the XDR structures used first.
#[test]
fn to_bytes() {
    let key = LedgerKey::ContractData(LedgerKeyContractData {
        contract: ScAddress::Contract(Hash(stellar_strkey::Contract::from_string("CDRBYAW4UHXWVBCM4MIYZNL2EAW4TEKLQKUS7SXO67BG4IWAHXIDW63A").unwrap().0)),
        key: ScVal::LedgerKeyContractInstance,
        durability: ContractDataDurability::Persistent
    });
    let mut hasher = Sha256::new();
    hasher.update(key.to_xdr(Limits::none()).unwrap());
    let result = hasher.finalize().as_slice().try_into().unwrap();
    println!("Your hash_xdr is {}", Hash(result).to_xdr_base64(Limits::none()).unwrap());
}
```

### Account Subscriptions

Account subscriptions allow you to start indexing operations, balances, and the account object of a certain Stellar account. These are mostly used for the Stellar "classic" side.

{% tabs %}
{% tab title="cURL" %}

```
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_TOKEN" \
     -d '{
          "publickey": "PUBLIC_KEY",
          "hydrate": true
         }' \
     http://172.232.157.194:3030/account
```

{% endtab %}

{% tab title="Javascript (Mercury SDK From PaltaLabs)" %}

```javascript
mercuryInstance.subscribeToFullAccount({
  address: "PUBLIC_KEY",
});
```

{% endtab %}
{% endtabs %}

Note that the `hydrate: bool` flag specifies whether you want to make a light catchup upon subscribing. This means that the latest operations and current balances of the public key will be queriable right after the subscription, even if these were emitted before the time of the subscription. 

{% hint style="info" %}
When specifying `hydrate: true`, if no account exists on the network with that public key, the backend will return an error.
{% endhint %}