# Add credits for inference

Use your SayGM account to add prepaid credits and send an inference request.

## Sign in

1. Sign in with the Bittensor coldkey you will use for deposits. Request a
   challenge for its SS58 address with POST https://account.saygm.com/v1/oauth/challenge:

```sh
ACCOUNT_API='https://account.saygm.com/v1'
CLIENT_ID='saygm-cli'
COLDKEY_ADDRESS='YOUR_SS58_COLDKEY_ADDRESS'
curl -sS --fail-with-body "$ACCOUNT_API/oauth/challenge" \
  -H 'Content-Type: application/json' \
  --data "{\"address\":\"$COLDKEY_ADDRESS\"}"
```

   Run the returned sign_command with the same coldkey before expires_in
   seconds elapse. Copy the exact nonce and sign it:

```sh
NONCE='PASTE_EXACT_NONCE'

# btcli 9.x
btcli wallet sign --wallet-name default --message "$NONCE" --no-use-hotkey --json-output

# btcli 11.x
btcli wallet sign --wallet default --message "$NONCE" --json
```

   Submit the signed message with the Bittensor signature token grant. Use the
   sign output's signed_message hex as SIGNATURE, remove line breaks, and
   check that signer_address matches COLDKEY_ADDRESS:

```sh
SIGNATURE='PASTE_SIGNED_MESSAGE_HEX'
curl -sS --fail-with-body "$ACCOUNT_API/oauth/token" \
  --data-urlencode 'grant_type=urn:taostats:params:oauth:grant-type:bittensor-signature' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "nonce=$NONCE" \
  --data-urlencode "address=$COLDKEY_ADDRESS" \
  --data-urlencode "signature=$SIGNATURE" \
  --data-urlencode 'device_name=saygm-agent'
```

   The token response contains access_token, refresh_token, and expires_in.
   Save the token pair. The coldkey used to sign in identifies your account:

```sh
ACCESS_TOKEN='PASTE_ACCESS_TOKEN'
REFRESH_TOKEN='PASTE_REFRESH_TOKEN'
```

2. Create a SayGM inference key with POST https://account.saygm.com/v1/keys and the bearer
   token. Its secret is shown once; store it securely as API_KEY:

```sh
curl -sS --fail-with-body -X POST "$ACCOUNT_API/keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"agent"}'
API_KEY='PASTE_SECRET'
```

## Add credits

### TAO deposit address

Request this account's permanent address with POST https://account.saygm.com/v1/wallet-deposits/address and
a bearer token. The endpoint takes no request body:

```sh
curl -sS --fail-with-body -X POST "$ACCOUNT_API/wallet-deposits/address" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response contains address, network, minimum_usd, and automatic_limit_usd. Repeated calls
return the same address for this account. Send TAO from any wallet or exchange to this address
on the listed network. The minimum deposit is $0.01. Keep each deposit at or below the
automatic_limit_usd shown in the response. Deposits credit after finality at the TAO price
recorded for that block, rounded down to whole cents.

### Alpha transfer

The wallet that signed in is linked for Alpha deposits. Send Alpha for the listed subnet from
that coldkey to the configured recipient. Leave enough TAO in the wallet for the transaction fee.

```sh
RECIPIENT='5FqbWhtCvoSD3X3iNxyWXogrKGmeVLnjZXoNWPx16yErYQd9'
ALPHA='<ALPHA>'
HOTKEY='<STAKE_HOTKEY_SS58>'

# btcli 9.x Alpha: subnet 28, same hotkey
btcli stake transfer --wallet-name default --network 'finney' --hotkey "$HOTKEY" \
  --origin-netuid '28' --dest-netuid '28' --dest "$RECIPIENT" --amount "$ALPHA"

# btcli 11.x Alpha: subnet 28, same hotkey
btcli stake transfer --wallet default --network 'finney' --netuid '28' --hotkey "$HOTKEY" \
  --dest "$RECIPIENT" --amount "$ALPHA"
```

Choose the command for your btcli version. These commands match btcli 9.23.2 and btcli 11.3.0;
check --help for your installed version.

### Gamma

For Gamma credit, follow the [Gamma guide](https://saygm.com/gamma.md).

### USDC on Ethereum mainnet

Request the account's assigned address with POST https://account.saygm.com/v1/wallets/usdc/assign
and a bearer token:

```sh
curl -sS --fail-with-body -X POST "$ACCOUNT_API/wallets/usdc/assign" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response contains eth_address, wallet_index, and created_at. Repeat calls
return the same address for this account. Send USDC from any EVM wallet to
eth_address. The indexer waits for two Ethereum block confirmations. The
minimum deposit is 1 USDC, and credited value is rounded down to whole cents.

### x402 Alpha on subnet 28 payment

Send POST https://account.saygm.com/v1/payments/x402 with a purchase amount:

```sh
curl -i -sS -X POST "$ACCOUNT_API/payments/x402" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"amount_cents":500}'
```

A request without a proof returns a 402 response with payment requirements and
a Sign-In-With-X challenge. On mainnet, use the relayed payment quote. GM broadcasts the signed transaction and credits the account after settlement.
For a relayed quote in accepts or the x-402-relayed-direct response header,
use a Substrate signing library to construct and sign the quoted extrinsic
without broadcasting it. Resend the same request with the PAYMENT-SIGNATURE
proof and the signed challenge in SIGN-IN-WITH-X. Use the quote's resource URL
and network when constructing the proofs. If the response is 202, replay the
identical request with the same signed bytes while settlement is pending.
See the [Account API OpenAPI](https://account.saygm.com/v1/openapi.json) for request, quote,
proof, and response shapes.

### Card or browser wallet

For card or browser wallet, send your human to
[https://saygm.com/dashboard/credits](https://saygm.com/dashboard/credits).

## Check the balance

Poll GET https://account.saygm.com/v1/balance with the bearer access token. If polling
outlasts the access token, read expires_in and refresh with the current refresh
token before the next poll. Each successful refresh rotates the refresh token;
store the new pair.

```sh
curl -sS --fail-with-body "$ACCOUNT_API/balance" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS --fail-with-body "$ACCOUNT_API/oauth/token" \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"
ACCESS_TOKEN='PASTE_NEW_ACCESS_TOKEN'
REFRESH_TOKEN='PASTE_NEW_REFRESH_TOKEN'
```

If a refresh response is lost, sign in again with a fresh coldkey challenge.

## Send an inference request

Choose an available model from GET https://api.saygm.com/v1/models?api_shape=....
Send each request to the endpoint that matches the model maker:

- Claude: list models with GET https://api.saygm.com/v1/models?api_shape=messages and
  POST https://api.saygm.com/v1/messages with x-api-key and anthropic-version:
  2023-06-01 headers.
- Gemini: list models with GET https://api.saygm.com/v1/models?api_shape=generateContent
  and POST https://api.saygm.com/v1beta/models/{model}:generateContent.
- Other makers: list models with GET
  https://api.saygm.com/v1/models?api_shape=chat.completions and POST
  https://api.saygm.com/v1/chat/completions.

Use the model's exact id and choose one whose available field is true. The API
shape identifies the matching endpoint. For a chat completions model, send a
request with the SayGM API key:

```sh
curl -sS --fail-with-body 'https://api.saygm.com/v1/models?api_shape=chat.completions' \
  -H "Authorization: Bearer $API_KEY"
MODEL='PASTE_AVAILABLE_CHAT_MODEL_ID'
curl -sS --fail-with-body 'https://api.saygm.com/v1/chat/completions' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"model\":\"$MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"
```
