Quickstart

Start without a key

No header. The same endpoints a keyed caller uses. Thirty requests a minute is the unkeyed budget. new Reserve("testnet") pins the testnet URL.

• Site https://reserve.cavos.xyz
• Testnet https://reserve.cavos.xyz/testnet
• Mainnet https://reserve.cavos.xyz/mainnet

SDK

npm install @cavos/reserve @stellar/stellar-sdk

import { Reserve } from "@cavos/reserve";

const reserve = new Reserve("testnet");
// Mainnet: new Reserve("mainnet")

const { hash } = await reserve.pay({
  source,
  destination,
  amount: "10",
  token: "USDC:GA5ZSEJ…",
  maxSend: "0.05",
}, (xdr, { networkPassphrase }) =>
  wallet.signTransaction(xdr, { networkPassphrase }),
);

The SDK keeps the request you made and refuses a quote, or a built transaction, that does not match it. Do not call /v1/build yourself and sign the bytes.

Activate an account with a token

Someone with no account cannot hold XLM and cannot source a transaction. Pay them a claimable balance first. Their first call creates the account, opens the trustline, and claims, in one transaction. Reserves and fees come out of the claimed token. Never create the account empty: sponsored reserves on an address that never comes back cannot be recovered.

await reserve.activate({
  address: newAddress,
  token: "USDC:GA5ZSEJ…",
  balanceId,
  maxSend: "5",
}, sign);

1.5 XLM of opening reserves, paid in the token. The claimable balance has to cover that plus the fee.

curl

curl -s https://reserve.cavos.xyz/testnet/v1/quote \
  -H 'content-type: application/json' \
  -d '{
    "source": "G…",
    "fee_token": "native",
    "ops": [{
      "type": "payment",
      "destination": "G…",
      "asset": "native",
      "amount": "10"
    }]
  }'

GET /testnet/v1/tokens and GET /mainnet/v1/tokens list what this host accepts. Testnet here is XLM only. Mainnet includes Circle USDC.

Need more than thirty requests a minute? Raise the limit, sign once, and send Authorization: Bearer on the same calls.