AgentSats API ReferenceCLI v0.1.0Node 20.10+

Reference docs

Agent-safe CLI access to paid APIs

Use AgentSats to discover bitcoinagent services, call GET and POST endpoints, return deterministic JSON, and handle x402 STX payment challenges from scripts or agent runtimes.

Explore endpoints npm package

Quick start

npx agentsats --help
npx agentsats services --json
npx agentsats service-endpoints --service twitter --json
npx agentsats twitter-tweets --user-id 2455740283 --count 20 --json

Overview Installation Output Modes Discovery Named Commands Generic Calls Wallets x402 Flow Errors JSON Contract Completions

Overview

How AgentSats works

Discover

List services and service endpoints before making paid requests. Discovery endpoints work well as agent planning tools.

Call

Run named commands for common routes or use api-call for the expanded API surface.

Parse

JSON mode returns one stable object on stdout, with no banner, spinner, prompt, ANSI noise, or extra logs.

Get Started

Installation

AgentSats is published as agentsats. Run it with npx, install it globally, or invoke it as a subprocess in your agent runtime.

Install and inspect

npx agentsats --help
npx agentsats services --json
npx agentsats wallet --json

Endpoint commands call BITCOINAGENT_API_URL when set, otherwise https://agentsats.stacksx402.com/. Every API command can override this with --api-url <url>.

Contract

Output modes

Human

Default mode. Includes the AgentSats banner and readable Clack summaries.

Plain

Add --plain for key-value text without decoration.

JSON

Add --json. JSON mode wins over plain mode and is the automation contract.

Help safety

--json --help returns a structured VALIDATION_ERROR. Help without --json exits with code 0.

API Reference

Discovery endpoints

Discovery commands expose the available services and their endpoint metadata. Use these before selecting paid data routes.

GET/health

Check whether the bitcoinagent API is reachable.

CLI request

npx agentsats health --json

Query Params

No parameters required.

Responses

Unwrapped API response, commonly { "status": "ok" }.

GET/api/v1/services

List available service groups and whether paid endpoints are enabled.

CLI request

npx agentsats services --json

Query Params

No parameters required.

Responses

Service metadata under data.response, plus provider when the API envelope includes meta.provider.

GET/api/v1/services/:service/endpoints

Discover endpoint paths, required query parameters, and payment metadata for a service.

CLI request

npx agentsats service-endpoints --service twitter --json

Query Params

Name

Type

Description

service

string

Required. Service name such as twitter, linkedin, airbnb, or google-flights.

Responses

Endpoint definitions returned by the API, unwrapped from the API envelope.

API Reference

Named commands

Named commands are convenience wrappers for common TikTok and Twitter/X routes. They all support --api-url, --plain, and --json.

Command

Route

Required flags

Use

tiktok-profile

GET /api/v1/tiktok/user/info

--username <username>

Fetch TikTok profile data by username.

tiktok-videos

GET /api/v1/tiktok/user/posts

--sec-uid <secUid> [--count <n>] [--cursor <cursor>]

Fetch TikTok user posts.

twitter-profile

GET /api/v1/twitter/profile

--username <username>

Fetch X/Twitter profile data.

twitter-highlights

GET /api/v1/twitter/highlights

--user-id <id> [--count <n>]

Fetch highlighted posts by user ID.

twitter-tweets

GET /api/v1/twitter/tweets

--user-id <id> [--count <n>]

Fetch tweets by user ID.

twitter-followings

GET /api/v1/twitter/followings

--user-id <id> [--count <n>]

Fetch followed accounts by user ID.

API Reference

Generic endpoint calls

Use service-scoped commands when the endpoint belongs to a known service. Use api-call for full-path GET and POST requests.

airbnbbookinggoogle-flightsinstagramlinkedintiktoktwitter

Service command

npx agentsats airbnb \
  --endpoint stays/search \
  --query placeId=ChIJVTPokywQkFQRmtVEaUZlJRA \
  --json

Full path command

npx agentsats api-call \
  --method POST \
  --path /api/v1/google-flights/booking/url \
  --body-json '{"token":"booking-token"}' \
  --json

Endpoint paths reject network-path references, backslashes, invalid percent encoding, and . or .. segments before any request is made. Put query values in repeated --query key=value flags, not inside --endpoint.

Payments

Wallet configuration

Wallets are optional for free endpoints and required for automatic x402 payment signing. AgentSats supports private-key wallets and Open Wallet Standard preview wallets.

Private key wallet

AGENTSATS_WALLET_PROVIDER=private-key
STACKS_NETWORK=mainnet
STACKS_PRIVATE_KEY=your-stacks-private-key

OWS wallet

AGENTSATS_WALLET_PROVIDER=ows
OWS_WALLET=agentsats-mainnet
OWS_CHAIN=stacks:1
OWS_CLI=/path/to/ows
OWS_STACKS_KEY_ENCODING=uncompressed
OWS_PASSPHRASE=

OWS Stacks preview setup

npx agentsats wallet setup \
  --provider ows \
  --preview-stacks \
  --wallet agentsats-mainnet \
  --network mainnet \
  --json

Preview warning

Stacks support in OWS is still under development.

Payments

x402 STX flow

Challenge

Paid endpoints return HTTP 402 with a base64 JSON payment-required header.

Sign

AgentSats selects a compatible STX payment option and signs a facilitator-bound Stacks transfer.

Retry

The CLI retries with payment-signature. If settlement is pending, it retries once more with the same signature.

PAYMENT_REQUIRED response

{
  "success": false,
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Payment is required for this endpoint.",
    "details": {
      "statusCode": 402,
      "endpoint": "/api/v1/twitter/profile",
      "paymentRequired": {
        "accepts": [
          {
            "scheme": "exact",
            "network": "stacks:1",
            "asset": "STX",
            "amount": "1000"
          }
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2026-04-16T00:00:00.000Z",
    "mode": "json"
  }
}

Schema

JSON contract

JSON output is always a CliResponse<T>. Successful commands include data; failed commands include error. The meta object always includes timestamp and mode.

Success response

{
  "success": true,
  "data": {
    "method": "GET",
    "endpoint": "/api/v1/twitter/profile",
    "statusCode": 200,
    "provider": "rapidapi",
    "response": {
      "Username": "MrBeast",
      "DisplayName": "MrBeast"
    },
    "timestamp": "2026-04-16T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-16T00:00:00.000Z",
    "mode": "json"
  }
}

Operations

Errors and exit codes

0

Success, including non-JSON help output.

1

Validation, payment-required, or internal errors.

2

Not found.

Codes

VALIDATION_ERROR, NOT_FOUND, PAYMENT_REQUIRED, INTERNAL_ERROR.

Tools

Shell completions

Generate completions

npx agentsats complete zsh > ~/.agentsats-completion.zsh
npx agentsats complete bash > ~/.agentsats-completion.bash

Source on GitHub Package on npm

Request Console

Shell

npx agentsats twitter-profile \
  --username MrBeast \
  --api-url https://agentsats.stacksx402.com \
  --json

Response

{
  "success": true,
  "data": {
    "method": "GET",
    "endpoint": "/api/v1/twitter/profile",
    "statusCode": 200,
    "provider": "rapidapi",
    "response": {
      "Username": "MrBeast",
      "DisplayName": "MrBeast"
    },
    "timestamp": "2026-04-16T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-16T00:00:00.000Z",
    "mode": "json"
  }
}

API Base

https://agentsats.stacksx402.com