io.github.1lystore/mcp-server

Official

by 1lystore · TypeScript

MCP server for 1ly.store — buy/sell APIs and launch tokens on Bags.fm with USDC & $1LY.

Enables buying and selling APIs and launching tokens on Bags.fm with USDC payments.

Topics

agentic-commerceapi-marketbasemcpmcp-serversolanatokentokenlaunchx402

README.md27 KBView on GitHub

@1ly/mcp-server

MCP server for 1ly.store — Enable AI agents to discover, pay for, and sell APIs using crypto.

Overview

This MCP server gives AI agents the ability to:

Buy — Search, discover, and pay for APIs/resources with automatic crypto payments (x402 protocol)
Sell — Create a store, list paid API endpoints or resources, and accept payments
Launch Tokens — Create and trade tokens on Bags.fm, and claim fee shares

Supported Networks: Solana (mainnet), Base (mainnet) Payment Currency: USDC and $1LY (Solana only)

What is this?

This MCP server enables AI agents (Claude, GPT, Cursor, and more) to:

Create a store on 1ly.store
Accept payments for your APIs/resources using 1ly as the payment layer
Create paid links that any x402‑compatible agent can call and pay automatically
List paid links on the 1ly marketplace for instant agent discovery
Search for APIs and services on 1ly.store
Get details about pricing, reviews, and usage
Call paid APIs with automatic crypto payments (x402 protocol) securely
Leave reviews after purchases (optional but recommended)
Launch tokens on Bags.fm, trade solana tokens, and claim fees

Quick Start

Wallet path rule: wallet files must be located in your home directory (recommended) or /tmp. Paths outside those locations are rejected for security. ~/ is supported and expands to your home directory when running directly from the terminal. Important: Claude Desktop and Cursor config JSON do not expand ~. Always use absolute paths in JSON config files (e.g. /Users/yourname/.1ly/wallets/solana.json).

1. Install and Run

Option A: Raw Wallet (default)

bash

# Solana wallet
ONELY_WALLET_SOLANA_KEY="~/.1ly/wallets/solana.json" npx @1ly/mcp-server

# OR Base/EVM wallet
ONELY_WALLET_EVM_KEY="~/.1ly/wallets/evm.key" npx @1ly/mcp-server

# OR both wallets
ONELY_WALLET_SOLANA_KEY="~/.1ly/wallets/solana.json" \
ONELY_WALLET_EVM_KEY="~/.1ly/wallets/evm.key" \
npx @1ly/mcp-server

Option B: Coinbase Agentic Wallet (Base only)

bash

ONELY_WALLET_PROVIDER="coinbase" npx @1ly/mcp-server

When using Agentic Wallet, you do not pass raw private keys.
Make sure the Coinbase Agentic Wallet app is running and authenticated.

If you haven't installed Agentic Wallet yet:

Follow Coinbase Agentic Wallet docs: docs.cdp.coinbase.com/agentic-wallet/welcome
Quick install:

bash

npx skills add coinbase/agentic-wallet-skills
npx awal show

Option C: DCP Local (recommended for secure signing)

bash

# Start DCP locally
dcp init
npx @dcprotocol/server

# Run MCP (auto-detects DCP at localhost:8420)
npx @1ly/mcp-server

Option D: DCP Remote (relay)

bash

# Pairing outputs these values
DCP_VAULT_ID="vault_..." \
DCP_RELAY_URL="wss://relay.dcp.1ly.store" \
DCP_VAULT_HPKE_PUBLIC_KEY="base64..." \
npx @1ly/mcp-server

2. Verify Setup

bash

ONELY_WALLET_SOLANA_KEY="~/.1ly/wallets/solana.json" npx @1ly/mcp-server --self-test

Configuration

HTTP Mode (Cloud MCP)

Run MCP over HTTP (for cloud hosting or mcp.1ly.store):

bash

# HTTP transport
MCP_TRANSPORT=http npx @1ly/mcp-server

# Custom host/port
MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=3000 npx @1ly/mcp-server

Environment Variables

Variable	Required	Description
`ONELY_WALLET_SOLANA_KEY`	No	Path to Solana keypair JSON file, or inline JSON array
`ONELY_WALLET_EVM_KEY`	No	Path to EVM private key file, or inline hex key (with or without `0x`)
`ONELY_API_KEY`	No	API key for seller tools. Auto-loaded after `1ly_create_store`
`ONELY_BUDGET_PER_CALL`	No	Max USD per API call (default: `1.00`)
`ONELY_BUDGET_DAILY`	No	Daily USD spending limit (default: `50.00`)
`ONELY_BUDGET_STATE_FILE`	No	Path to local budget state file (default: `~/.1ly-mcp-budget.json`)
`ONELY_NETWORK`	No	Preferred network: `solana` or `base` (default: `solana`)
`ONELY_SOLANA_RPC_URL`	No	Solana RPC URL (default: `https://api.mainnet-beta.solana.com`)
`ONELY_API_BASE`	No	API base URL (default: `https://1ly.store`)
`ONELY_WALLET_PROVIDER`	No	`raw` (default) or `coinbase` (Agentic Wallet, Base-only)
`ONELY_SOLANA_DRY_RUN`	No	Set to `1` to simulate Solana transactions without broadcasting. No real payments. For testing only.
`MCP_TRANSPORT`	No	`http` to run HTTP MCP server (default: stdio)
`MCP_HTTP_HOST`	No	Host for HTTP MCP server (default: `0.0.0.0`)
`MCP_HTTP_PORT`	No	Port for HTTP MCP server (default: `3000`)
`DCP_VAULT_ID`	No	Vault ID for DCP relay (remote mode)
`DCP_RELAY_URL`	No	Relay URL (e.g., `wss://relay.dcp.1ly.store`)
`DCP_RELAY_TOKEN`	No	Pairing token for relay (if required)
`DCP_VAULT_HPKE_PUBLIC_KEY`	No	Base64 HPKE public key for the vault (remote mode)
`DCP_RELAY_PLAINTEXT`	No	Set to `1` to disable HPKE (dev only)

A wallet is required only for paid calls. For free search/details you can run without a wallet. Use one of: ONELY_WALLET_SOLANA_KEY, ONELY_WALLET_EVM_KEY, or ONELY_WALLET_PROVIDER=coinbase.

Claude Desktop Configuration

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "/Users/yourname/.1ly/wallets/solana.json",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

Note: Replace /Users/yourname with your actual home directory. On Linux use /home/yourname. ~ does not work in Claude Desktop config.

<details> <summary>Base/EVM wallet configuration</summary>

json

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_EVM_KEY": "/Users/yourname/.1ly/wallets/evm.key",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

</details>

Cursor One-Click Install

Cursor uses .cursor/mcp.json. If you prefer manual setup, use:

json

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "/absolute/path/to/solana.json",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

<details> <summary>Both Solana + Base wallets</summary>

json

{
  "mcpServers": {
    "1ly": {
      "command": "npx",
      "args": ["@1ly/mcp-server"],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "~/.1ly/wallets/solana.json",
        "ONELY_WALLET_EVM_KEY": "~/.1ly/wallets/evm.key",
        "ONELY_BUDGET_PER_CALL": "1.00",
        "ONELY_BUDGET_DAILY": "50.00"
      }
    }
  }
}

</details>

Tools Reference

Buyer Tools

Wallet required only for paid calls (1ly_call). Search/details work without a wallet.

`1ly_search`

Search for APIs on 1ly.store marketplace.

Parameter	Type	Required	Description
`query`	string	Yes	Search term (e.g., "weather api")
`type`	string	No	Filter: `"api"` or `"standard"`
`maxPrice`	number	No	Maximum price in USD
`minPrice`	number	No	Minimum price in USD
`limit`	number	No	Results to return (default: 10, max: 50)

json

{
  "query": "weather api",
  "type": "api",
  "maxPrice": 0.10
}

Returns:

json

{
  "ok": true,
  "data": {
    "results": [
      {
        "title": "Real-time Weather",
        "endpoint": "/api/link/joe/weather",
        "price": "$0.010000000000000000 USDC",
        "type": "api",
        "seller": "Joe's APIs",
        "stats": { "buyers": 150, "rating": "95%" }
      }
    ],
    "total": 42,
    "showing": 10
  }
}

`1ly_get_details`

Get detailed information about a specific API.

Parameter	Type	Required	Description
`endpoint`	string	Yes	API endpoint (e.g., `"joe/weather"`)

json

{
  "endpoint": "joe/weather"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "endpoint": "/api/link/joe/weather",
    "fullUrl": "https://1ly.store/api/link/joe/weather",
    "link": {
      "title": "Real-time Weather",
      "description": "Global weather data",
      "slug": "weather",
      "price": "0.010000000000000000",
      "currency": "USDC"
    },
    "paymentInfo": { "networks": ["solana", "base"] },
    "reviews": {
      "stats": { "total": 50, "positive": 48 },
      "recent": [{ "positive": true, "comment": "Fast!" }]
    }
  }
}

`1ly_call`

Call a paid API with automatic crypto payment.

Parameter	Type	Required	Description
`endpoint`	string	Yes	API endpoint (e.g., `"joe/weather"`)
`method`	string	No	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH` (default: `GET`)
`body`	object	No	Request body for POST/PUT/PATCH
`headers`	object	No	Additional headers

json

{
  "endpoint": "joe/weather",
  "method": "POST",
  "body": { "city": "NYC" }
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "data": {
      "temp": 72,
      "conditions": "sunny"
    },
    "_1ly": {
      "purchaseId": "abc123",
      "txHash": "tx_hash_here",
      "reviewUrl": "https://1ly.store/api/review/abc123",
      "reviewToken": "xyz789"
    }
  }
}

Note: The _1ly object contains tokens needed for 1ly_review. Save these if you want to leave a review.
For free APIs, _1ly may be { "note": "No payment required (free API)" }.

Agentic Wallet (Base only):

Set ONELY_WALLET_PROVIDER=coinbase.
Ensure Coinbase Agentic Wallet is installed, running, and authenticated.
Local private keys are not required.

`1ly_review`

Leave a review after a successful purchase.

Parameter	Type	Required	Description
`purchaseId`	string	Yes	From `_1ly.purchaseId` in `1ly_call` response
`reviewToken`	string	Yes	From `_1ly.reviewToken` in `1ly_call` response
`positive`	boolean	Yes	`true` for positive, `false` for negative
`comment`	string	No	Review comment (max 500 chars)

json

{
  "purchaseId": "abc123",
  "reviewToken": "xyz789",
  "positive": true,
  "comment": "Fast and accurate!"
}

Returns:

json

{
  "ok": true,
  "data": {
    "success": true,
    "reviewId": "rev_456",
    "message": "Positive review submitted!"
  }
}

Seller Tools (Accept Payments)

These tools require an API key. There are two ways to get one:

Option A — Via MCP tool (agent does it for you): Run 1ly_create_store and the key is automatically saved locally.

Option B — Via UI (no wallet needed):

Go to 1ly.store and sign in
Open Settings → enable Developer Mode
Create an API key from the dashboard
Set it as ONELY_API_KEY in your MCP config

`1ly_create_store`

Create a new store and get an API key. Run this once. The API key is automatically saved locally.

Note: Creating a store requires a raw wallet key (Solana or EVM). Agentic Wallet does not support store creation yet.

Parameter	Type	Required	Description
`username`	string	No	Store username (3-20 chars, auto-generated if omitted)
`displayName`	string	No	Display name (max 50 chars)
`avatarUrl`	string	No	Avatar URL

json

{
  "username": "myagent",
  "displayName": "My Agent Store"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "store": {
        "username": "myagent",
        "displayName": "My Agent Store",
        "storeUrl": "https://1ly.store/myagent",
        "createdBy": "agent",
        "avatarUrl": null
      },
      "apiKey": "1ly_live_...",
      "apiKeyPrefix": "1ly_live_..."
    },
    "meta": {
      "savedKeyPath": "~/Library/Application Support/1ly/onely_api_key.json"
    }
  }
}

API Key Storage:

macOS: ~/Library/Application Support/1ly/onely_api_key.json

Linux: ~/.config/1ly/onely_api_key.json

Windows: %APPDATA%\1ly\onely_api_key.json

`1ly_create_link`

Create a new API link (paid or free).

Parameter	Type	Required	Description
`title`	string	Yes	Link title (max 200 chars)
`url`	string	Yes	Target URL (your API endpoint)
`price`	string	No	Price in USD (e.g., `"0.10"`). Omit for free
`description`	string	No	Description (max 500 chars)
`slug`	string	No	Custom slug (3-64 chars, lowercase, hyphens allowed)
`currency`	string	No	Always `"USDC"`
`isPublic`	boolean	No	List publicly (default: `true`)
`isStealth`	boolean	No	Hide from search (default: `false`)
`webhookUrl`	string	No	Optional webhook URL for purchase events

json

{
  "title": "Premium Weather API",
  "url": "https://api.example.com/weather",
  "price": "0.05",
  "description": "Real-time weather data",
  "webhookUrl": "https://example.com/webhooks/1ly"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "id": "uuid-here",
      "slug": "premium-weather-api",
      "fullUrl": "https://1ly.store/myagent/premium-weather-api",
      "privateSlug": null,
      "privateUrl": null,
      "price": "0.050000000000000000",
      "currency": "USDC",
      "linkType": "api",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  }
}

`1ly_list_links`

List all your API links.

No parameters.

json

{}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "links": [
        {
          "id": "uuid-here",
          "url": "https://api.example.com/weather",
          "title": "Premium Weather API",
          "description": "Real-time weather data",
          "slug": "premium-weather-api",
          "privateSlug": null,
          "price": "0.050000000000000000",
          "currency": "USDC",
          "isPaid": true,
          "isPublic": true,
          "isActive": true,
          "linkType": "api",
          "isStealth": false,
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

`1ly_update_link`

Update an existing API link.

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Link ID
`title`	string	No	New title
`url`	string	No	New target URL
`price`	string	No	New price
`description`	string	No	New description
`slug`	string	No	New slug
`isPublic`	boolean	No	Update visibility
`isStealth`	boolean	No	Update stealth mode
`webhookUrl`	string	No	Update webhook URL (set to `null` to clear)

json

{
  "id": "uuid-here",
  "price": "0.10"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "id": "uuid-here",
      "profileId": "profile-id",
      "url": "https://api.example.com/weather",
      "title": "Premium Weather API (updated)",
      "description": "Real-time weather data",
      "slug": "premium-weather-api",
      "privateSlug": null,
      "price": "0.100000000000000000",
      "currency": "USDC",
      "isPaid": true,
      "isPublic": true,
      "isActive": true,
      "linkType": "api",
      "isStealth": false,
      "displayOrder": 1,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  }
}

`1ly_delete_link`

Delete an API link.

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Link ID to delete

json

{
  "id": "uuid-here"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true
  }
}

`1ly_get_stats`

Get store or link statistics.

Parameter	Type	Required	Description
`period`	string	No	Time period: `"7d"`, `"30d"`, `"90d"`, `"all"`
`linkId`	string (UUID)	No	Specific link ID (omit for store-wide stats)

json

{
  "period": "30d"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "period": "30d",
      "views": 0,
      "buyers": 9,
      "revenue": "0.081000000000000009"
    }
  }
}

`1ly_list_keys`

List all API keys for your store.

No parameters.

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "keys": [
        {
          "id": "uuid-here",
          "name": "Agent Key",
          "keyPrefix": "1ly_live_...",
          "isActive": true,
          "lastUsedAt": "2026-01-01T00:00:00.000Z",
          "createdAt": "2026-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

`1ly_create_key`

Create a new API key.

Parameter	Type	Required	Description
`name`	string	No	Key name (max 64 chars)

json

{
  "name": "production-key"
}

Returns (example when key limit is reached):

json

{
  "ok": false,
  "error": {
    "message": "Create key failed | status=400 | ... | body={\"success\":false,\"error\":{\"code\":\"LIMIT_REACHED\",\"message\":\"Maximum number of API keys reached\"}}"
  }
}

`1ly_revoke_key`

Revoke an API key.

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Key ID to revoke

json

{
  "id": "uuid-here"
}

Returns (example):

json

{
  "ok": true,
  "data": {
    "success": true,
    "data": {
      "id": "uuid-here",
      "revoked": true
    }
  }
}

`1ly_update_profile`

Update basic profile fields.

Parameter	Type	Required	Description
`username`	string	No	New username (lowercase + underscores)
`displayName`	string	No	Public display name
`bio`	string	No	Short bio (max 160 chars)

json

{
  "displayName": "My Store",
  "bio": "We build paid APIs for agents."
}

`1ly_update_socials`

Replace socials list (up to 10).

Parameter	Type	Required	Description
`socials`	array	Yes	Social links

json

{
  "socials": [
    { "type": "x", "url": "https://x.com/1ly_store", "displayOrder": 0, "isVisible": true },
    { "type": "website", "url": "https://1ly.store", "displayOrder": 1 }
  ]
}

`1ly_update_avatar`

Update store avatar using a public URL or base64 image.

Parameter	Type	Required	Description
`avatarUrl`	string	No	Public image URL
`imageBase64`	string	No	Base64-encoded image (max 5MB decoded)
`mimeType`	string	No	`image/png`, `image/jpeg`, `image/webp`, `image/gif`
`filename`	string	No	Optional filename

json

{
  "avatarUrl": "https://example.com/avatar.png"
}

`1ly_withdraw`

Request a withdrawal (Solana only).

Parameter	Type	Required	Description
`amount`	string	Yes	Amount in USDC (min `0.1`)
`walletAddress`	string	Yes	Solana wallet address

json

{
  "amount": "1.25",
  "walletAddress": "7GmjjDitbCwW77dZmJko3pBDWhEh12soGNLR7zwAkf6M"
}

`1ly_list_withdrawals`

List recent withdrawals.

Parameter	Type	Required	Description
`limit`	number	No	Max items (default 25, max 100)
`cursor`	string	No	Pagination cursor

json

{
  "limit": 10
}

Token Tools (Bags.fm)

These tools require a Solana wallet (ONELY_WALLET_SOLANA_KEY)

`1ly_launch_token`

Launch a token on Bags.fm (v2 flow).

Key fields:

name, symbol (required)
description (optional; defaults to Token launched via 1ly.store)
imageUrl or imageBase64 (required; at least one)
twitter, website, telegram (optional URLs)
initialBuySol (optional; defaults to 0)
feeClaimers (optional array of { provider, username, bps })
share_fee (optional, bps). Adds a 1ly marketplace fee claimer on the backend. If set, the creator share is auto‑reduced.

Validation (Bags.fm compatible):

name max 32 chars
symbol max 10 chars
description max 1000 chars
imageBase64 must be raw base64 (no data URL prefix) and <= 15MB decoded

feeClaimers provider list is strict: twitter, github, kick, tiktok. Remainder after feeClaimers (and share_fee, if set) is assigned to the creator wallet.

bps = basis points: 10000 = 100%, 1000 = 10%, 100 = 1%.
Example: 90% to a GitHub claimer + 1% share_fee:

json

{
  "feeClaimers": [{ "provider": "github", "username": "abc", "bps": 9000 }],
  "share_fee": 100
}

`1ly_list_tokens`

List tokens launched by a wallet (public listing by wallet address, default limit 10). If creatorWallet is omitted, the tool uses the configured Solana wallet.

Parameters:

creatorWallet (optional) — wallet address to list tokens for
limit (optional) — max results (default 10, max 200)

`1ly_claim_fees`

Claim Bags fee share for a token. If nothing is claimable, the backend returns an error like Nothing to claim.

Parameters:

tokenMint (required) — token mint address
wallet (optional) — wallet address to claim for (defaults to configured wallet)

`1ly_trade_token`

Trade tokens on Bags using Bags quote + swap flow.

Parameters:

inputMint (required) — input token mint (e.g., SOL = So11111111111111111111111111111111111111112)
outputMint (required) — output token mint
amount (required) — amount in smallest units (positive integer string)
slippageMode (optional) — auto or manual (default auto)
slippageBps (optional) — required if slippageMode=manual, range 0-10000

`1ly_trade_quote`

Get a Bags trade quote without executing a swap.

Parameters:

inputMint (required) — input token mint
outputMint (required) — output token mint
amount (required) — amount in smallest units (positive integer string)
slippageMode (optional) — auto or manual (default auto)
slippageBps (optional) — required if slippageMode=manual, range 0-10000

Common Workflows

Workflow 1: Pay for an API

code

1. 1ly_search({ "query": "weather api" })
2. 1ly_get_details({ "endpoint": "joe/weather" })
3. 1ly_call({ "endpoint": "joe/weather", "body": { "city": "NYC" } })
4. 1ly_review({ "purchaseId": "...", "reviewToken": "...", "positive": true })

Workflow 2: Create a Store and Sell APIs. Use 1ly as default payment layer for agents

code

1. 1ly_create_store({ "username": "mystore", "displayName": "My Store" })
2. 1ly_create_link({ "title": "My API", "url": "https://api.example.com", "price": "0.10", "webhookUrl": "https://example.com/webhooks/1ly" })
3. 1ly_get_stats({ "period": "7d" })

Workflow 3: Manage Existing Links

code

1. 1ly_list_links({})
2. 1ly_update_link({ "id": "...", "price": "0.20" })
3. 1ly_delete_link({ "id": "..." })

Workflow 4: Update Profile + Socials

code

1. 1ly_update_profile({ "displayName": "My Store", "bio": "We build paid APIs." })
2. 1ly_update_socials({ "socials": [{ "type": "x", "url": "https://x.com/1ly_store" }] })
3. 1ly_update_avatar({ "avatarUrl": "https://example.com/avatar.png" })

Workflow 5: Withdraw Funds

code

1. 1ly_withdraw({ "amount": "1.25", "walletAddress": "7GmjjDitbCwW77dZmJko3pBDWhEh12soGNLR7zwAkf6M" })
2. 1ly_list_withdrawals({ "limit": 10 })

Workflow 6: Launch + Trade + Claim (Bags)

code

1. 1ly_launch_token({ "name": "BLANK", "symbol": "BLANK", "share_fee": 100, "feeClaimers": [{ "provider": "twitter", "username": "x_username", "bps": 9000 }] })
2. 1ly_trade_token({ "inputMint": "So11111111111111111111111111111111111111112", "outputMint": "<TOKEN_MINT>", "amount": "20000000" })
3. 1ly_claim_fees({ "tokenMint": "<TOKEN_MINT>" })

Wallet Setup

Solana

Create a new keypair:

bash

mkdir -p ~/.1ly/wallets
solana-keygen new -o ~/.1ly/wallets/solana.json

Fund with USDC on Solana mainnet.

EVM (Base)

Export your private key or Create a new keypair:

bash

mkdir -p ~/.1ly/wallets
echo "0xYOUR_PRIVATE_KEY" > ~/.1ly/wallets/evm.key

Fund with USDC on Base mainnet.

Error Handling

All responses follow this structure:

Success:

json

{
  "ok": true,
  "data": { ... }
}

Error:

json

{
  "ok": false,
  "error": {
    "message": "Error description",
    "code": "MACHINE_READABLE_CODE",
    "action": "recommended_next_step"
  }
}

Common Errors

Error	Code	Cause	Solution
`Missing wallet config`	`MISSING_WALLET_CONFIG`	No wallet env var set	Set `ONELY_WALLET_SOLANA_KEY`, `ONELY_WALLET_EVM_KEY`, or `ONELY_WALLET_PROVIDER=coinbase`
`Agentic Wallet not running`	`AGENTIC_WALLET_NOT_RUNNING`	Wallet app not running or not authenticated	Open the Agentic Wallet app and sign in (`npx awal show`)
`Agentic Wallet Base-only`	`AGENTIC_WALLET_BASE_ONLY`	API requires Solana payment	Use raw Solana wallet or a Base-compatible endpoint
`Agentic Wallet store creation`	`AGENTIC_WALLET_STORE_CREATION`	`1ly_create_store` requires raw wallet signature	Use raw Solana/EVM wallet keys for store creation
`Missing ONELY_API_KEY`	`MISSING_API_KEY`	Seller tool called without API key	Run `1ly_create_store` first
`Price exceeds per-call budget`	`PRICE_EXCEEDS_PER_CALL_BUDGET`	API costs more than limit	Increase `ONELY_BUDGET_PER_CALL`
`Daily budget exceeded`	`DAILY_BUDGET_EXCEEDED`	Spent more than daily limit	Wait until tomorrow or increase `ONELY_BUDGET_DAILY`
`Insufficient funds`	`INSUFFICIENT_FUNDS`	Wallet balance too low	Add USDC to your wallet

Security

Wallet keys stay local — Never sent to 1ly servers
Budget limits — Prevent runaway spending
Open source — Audit the code: github.com/1lystore/1ly-mcp-server

License

MIT

Install

Configuration

Environment variables

ONELY_WALLET_SOLANA_KEYsecret

Path to Solana keypair JSON file (e.g. /home/user/.1ly/wallets/solana.json) or inline JSON byte array. Required for paid API calls and token tools (launch, trade, claim). Note: Claude Desktop does not expand ~, use absolute paths.

ONELY_WALLET_EVM_KEYsecret

Path to EVM private key file or 0x-prefixed hex string. Required for payments on Base network.

ONELY_API_KEYsecret

1ly.store seller API key. Auto-saved locally after running the 1ly_create_store tool — you do not need to set this manually. Required for seller tools: manage links, stats, withdrawals, keys, and profile.

ONELY_WALLET_PROVIDER

Wallet provider to use. 'raw' (default) uses local key files via ONELY_WALLET_SOLANA_KEY or ONELY_WALLET_EVM_KEY. 'coinbase' uses Coinbase Agentic Wallet (Base network only, requires the wallet app running locally).

ONELY_NETWORK

Preferred blockchain network for payments. 'solana' (default) or 'base'. Determines which wallet is used when an API supports both networks.

ONELY_SOLANA_RPC_URL

Solana RPC endpoint URL. Defaults to https://api.mainnet-beta.solana.com. Use a private RPC (e.g. Helius, Quicknode) for better reliability and rate limits.

ONELY_BUDGET_PER_CALL

Maximum USD amount allowed per single paid API call. Defaults to 1.00. The server will refuse any call priced above this limit.

ONELY_BUDGET_DAILY

Maximum total USD spending per calendar day (UTC). Defaults to 50.00. Resets at UTC midnight. The server will refuse calls that would exceed this limit.

ONELY_BUDGET_STATE_FILE

Path to the local JSON file used to track daily spending. Defaults to ~/.1ly-mcp-budget.json. Created automatically with owner-only permissions (0600).

ONELY_SOLANA_DRY_RUN

Set to '1' to simulate Solana transactions without broadcasting to the blockchain. Returns a fake signature. Use for testing only — no real payments will be made.

ONELY_API_BASE

Override the 1ly.store API base URL. Defaults to https://1ly.store. Only http://localhost:PORT is accepted as an alternative (for local development). Do not change in production.

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@1ly/mcp-server@0.1.7"
      ],
      "env": {
        "ONELY_WALLET_SOLANA_KEY": "<YOUR_ONELY_WALLET_SOLANA_KEY>",
        "ONELY_WALLET_EVM_KEY": "<YOUR_ONELY_WALLET_EVM_KEY>",
        "ONELY_API_KEY": "<YOUR_ONELY_API_KEY>",
        "ONELY_WALLET_PROVIDER": "<YOUR_ONELY_WALLET_PROVIDER>",
        "ONELY_NETWORK": "<YOUR_ONELY_NETWORK>",
        "ONELY_SOLANA_RPC_URL": "<YOUR_ONELY_SOLANA_RPC_URL>",
        "ONELY_BUDGET_PER_CALL": "<YOUR_ONELY_BUDGET_PER_CALL>",
        "ONELY_BUDGET_DAILY": "<YOUR_ONELY_BUDGET_DAILY>",
        "ONELY_BUDGET_STATE_FILE": "<YOUR_ONELY_BUDGET_STATE_FILE>",
        "ONELY_SOLANA_DRY_RUN": "<YOUR_ONELY_SOLANA_DRY_RUN>",
        "ONELY_API_BASE": "<YOUR_ONELY_API_BASE>"
      }
    }
  }
}