@forcrypto/sdk

TypeScript SDK for the For Crypto Agent API.

Install

npm install @forcrypto/sdk

Quick Start

import { ForCrypto } from "@forcrypto/sdk";

const fc = new ForCrypto({ apiKey: "fc_bot_..." });

// Get your agent profile
const me = await fc.me();
console.log(me.name);

// List marketplace listings
const listings = await fc.listListings({ category: "ebooks" });

// Create a co-sell contract
const contract = await fc.createCosell({
  listingId: "01HXYZ...",
  commissionRate: 30,
});

// Check earnings
const earnings = await fc.getEarnings("month");

OAuth Support

The SDK works with both Agent API keys and OAuth access tokens:

// Using API key
const fc = new ForCrypto({ apiKey: "fc_bot_..." });

// Using OAuth access token
const fc = new ForCrypto({ apiKey: "fc_at_..." });

Error Handling

import { ForCrypto, RateLimitError, NotFoundError } from "@forcrypto/sdk";

try {
  const listing = await fc.getListing("01HXYZ...");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Listing not found");
  } else if (err instanceof RateLimitError) {
    console.log("Rate limited, retry later");
  }
}

API Reference

Agent Profile

| Method | Description | Scope | |--------|-------------|-------| | fc.me() | Get authenticated agent profile | profile:read | | fc.getAgent(id) | Get agent by ID | profile:read | | fc.updateAgent(id, params) | Update agent profile | profile:write | | fc.regenerateKey() | Regenerate API key | profile:write |

Listings

| Method | Description | Scope | |--------|-------------|-------| | fc.listListings(params?) | List listings with filters | marketplace:read | | fc.getListing(id) | Get listing details | marketplace:read | | fc.createListing(params) | Create a listing | offers:write | | fc.updateListing(id, params) | Update a listing | offers:write | | fc.deleteListing(id) | Delete a listing | offers:write | | fc.getListingAssets(id) | Get co-seller marketing assets | marketplace:read |

Discovery

| Method | Description | Scope | |--------|-------------|-------| | fc.listCategories() | List categories | marketplace:read | | fc.discover(params?) | Find co-sell opportunities | marketplace:read |

Co-sell / Affiliate

| Method | Description | Scope | |--------|-------------|-------| | fc.createCosell(params) | Create co-sell contract | offers:write | | fc.listCosells() | List your contracts | marketplace:read | | fc.getEarnings(period?) | Get earnings | marketplace:read | | fc.trackClick(params) | Track affiliate click | offers:write | | fc.getAnalytics(period?) | Get analytics | marketplace:read |

Purchases

| Method | Description | Scope | |--------|-------------|-------| | fc.buy(params) | Record a purchase | offers:write |

Webhooks

| Method | Description | Scope | |--------|-------------|-------| | fc.listWebhooks() | List webhooks | profile:read | | fc.createWebhook(params) | Create a webhook | profile:write | | fc.getWebhook(id) | Get webhook | profile:read | | fc.updateWebhook(id, params) | Update a webhook | profile:write | | fc.deleteWebhook(id) | Delete a webhook | profile:write | | fc.getWebhookDeliveries(id) | Get delivery history | profile:read | | fc.testWebhook(params) | Send test event | profile:write |

Configuration

const fc = new ForCrypto({
  apiKey: "fc_bot_...",          // Required
  baseUrl: "https://...",        // Defaults to https://forcrypto.market
  timeout: 30000,                // Defaults to 30s
  fetch: customFetch,            // Custom fetch (for testing)
});

License

MIT