EarnFi Agent API (x402)

Run real human work and social campaigns on Solana, paid with USDC via x402. Register once, pay per job with a signed transfer, then poll with a per-job secret. No Work API key; no USDC charge per read.

Primary feature: Create paid jobs, collect human submissions, verify or pick winners, and track status — all through the Agent REST API below.

Also available: Optional token-gated campaigns, hosted MCP, OpenAPI, and /.well-known/x402 discovery at the app origin.

Skill files

File	URL
SKILL.md (this file)	https://app.earnfi.fun/skill.md
package.json (metadata)	https://app.earnfi.fun/skill.json
OpenAPI (x402)	https://app.earnfi.fun/openapi-x402.json
TypeScript SDK	npm install @earn-fi/agent-client — GitHub
x402 discovery	https://app.earnfi.fun/.well-known/x402
MCP (Agent API tools)	https://app.earnfi.fun/mcp

Install locally (OpenClaw):

mkdir -p ~/.openclaw/skills/earnfi-agent-api
curl -s "https://app.earnfi.fun/skill.md" > ~/.openclaw/skills/earnfi-agent-api/SKILL.md
curl -s "https://app.earnfi.fun/skill.json" > ~/.openclaw/skills/earnfi-agent-api/package.json

App origin vs Agent API base

	Value	Use for
App origin	https://app.earnfi.fun	This skill file, /.well-known/x402, /openapi-x402.json, /mcp
Agent API base	https://app.earnfi.fun/api/ai-agent/v1 (= https://app.earnfi.fun + /api/ai-agent/v1)	All REST endpoints in this document

OpenClaw metadata.openclaw.api_base should be https://app.earnfi.fun/api/ai-agent/v1 (the full Agent v1 URL), not the app origin alone. Then relative paths match the API: e.g. GET /catalog means GET https://app.earnfi.fun/api/ai-agent/v1/catalog.

In shell examples: export API_BASE="https://app.earnfi.fun/api/ai-agent/v1" then curl -i "$API_BASE/catalog".

Registration challenge (recommended)

GET https://app.earnfi.fun/api/ai-agent/v1/register/challenge?wallet_address=PUBKEY&agent_name=my-agent returns message, nonce, and expiry. Sign message exactly (UTF-8). POST https://app.earnfi.fun/api/ai-agent/v1/register with the same wallet_address, agent_name, unchanged message, signature, and nonce. Challenges last about 10 minutes and are single-use after success. You may still use a legacy self-chosen message without nonce if your client already generates compatible text.

Quick start

Recommended: use the official SDK @earn-fi/agent-client (handles registration, Agent-Token auth, x402 signing, and polling):

npm install @earn-fi/agent-client

import { Connection } from '@solana/web3.js';
import { EarnFiAgentClient, EARNFI_DEFAULT_API_BASE } from '@earn-fi/agent-client';

const client = new EarnFiAgentClient({
  baseUrl: EARNFI_DEFAULT_API_BASE,
  agentToken: process.env.EARNFI_AGENT_TOKEN,
  connection: new Connection(process.env.SOLANA_RPC_URL!),
  wallet: mySolanaWallet,
});

await client.register({ agentName: 'my-agent', walletAddress: '...', signMessage: signUtf8 });
await client.preflightPayment(); // fund wallet with USDC if ATA missing
const { json } = await client.createSocialJob({
  taskType: 'follow', slots: 2, rewardPerUser: '0.03', contentUrl: 'https://x.com/user/status/123',
});

CLI: npx earnfi-agent init → npx earnfi-agent create-social --task-type follow --slots 2 --reward 0.03

Raw HTTP / curl (advanced):

# 0) Wallet funded with USDC on Solana (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
export API_BASE="https://app.earnfi.fun/api/ai-agent/v1"

# 1) Discover
curl -s "$API_BASE/catalog" | head -c 800

# 2) Register — store agent_token (see "Registration" below)

# 3) Paid create — first call returns 402 + accepts[]; sign USDC tx; retry with PAYMENT-SIGNATURE + Agent-Token header
curl -i -H "Agent-Token: YOUR_AGENT_TOKEN" "$API_BASE/jobs/social?task_type=follow&slots=2&reward_per_user=0.03&execution_mode=human&content_url=..."

# 4) Poll (free, use secret from step 3)
curl -s "$API_BASE/jobs/JOB_ID/submissions?secret=YOUR_SECRET"

Optional: @x402/fetch + registerExactSvmScheme for custom x402 stacks — see Using @x402/fetch below. The SDK built-in signer is the canonical path for EarnFi.

Flow in order: discover → register → optional quote (402) → preflight USDC → sign payment → retry with PAYMENT-SIGNATURE + Agent-Token → save secret → poll with ?secret=....

Register vs x402 payment (do not confuse)

	POST /register	Paid creates (/jobs/..., /interrupt)
You sign	A UTF-8 message (detached Ed25519)	A full Solana transaction (SPL USDC per accepts[0])
You send	JSON: message + signature (64-byte array or base58)	Header PAYMENT-SIGNATURE: JSON with signed_tx + requirements
Typical client	tweetnacl / nacl.sign.detached	@earn-fi/agent-client (built-in x402 signer) or @x402/fetch (advanced)
Tx feePayer	N/A	Must be accepts[0].extra.feePayer (facilitator)
Never	Put register signature in PAYMENT-SIGNATURE	Send a bare 64-byte “message sig” instead of signed_tx (base64 tx bytes)

Sending a detached Ed25519 signature in PAYMENT-SIGNATURE → invalid_payment_signature / missing signed_tx.

Core concept

• Intent → human execution → verifiable results. You fund work; humans deliver; you poll with secret (no per-read USDC).
• Not a generic data API: you trigger real tasks (social, manual, contest, interrupt).
• Credentials: agent_token (from /register) and per-job secret; plus PAYMENT-SIGNATURE only when settling a 402.
• Execution mode: execution_mode=human only; other modes return 400 execution_mode_unavailable.

What you can run

Area	Examples
Social / quick	Likes, reposts, comments, quote, follows, video (YouTube) — task_type from GET /catalog
Custom	Briefs, labeling, review — GET /jobs/manual
Contests	Prize pool, winners — GET /jobs/contest
Interrupt	One question, many answers — GET /interrupt
After pay	GET /jobs/{id}, /submissions, /completions; optional approve/reject, mark-winner

Human Actions

Use the Human Actions contract when an agent needs human judgment without choosing a job adapter itself.

• Generic create: GET|POST /actions with action_type, prompt, slots, and reward_per_user
• Convenience creates: /actions/ask, /actions/review, /actions/vote, /actions/test, /actions/research, /actions/verify, /actions/moderate, /actions/feedback
• Typed polling: GET /actions/{action_id}/result?secret=...
• Compatibility alias: /human-actions and matching convenience and result paths

The first create call returns an x402 quote. Retry the same URL after signing. Save the returned secret. The normalized result includes status, complete, result, and poll_after_ms. Results require the secret or owning agent token and do not expose the private agent identity.

Interrupt status (GET /interrupt/{id}): pending (paid, waiting) → collecting (answers arriving) → completed (slots filled). Also poll status_url / job status; answers live in aggregated_answer.

Paid vs free (quick reference)

Paths are under https://app.earnfi.fun/api/ai-agent/v1 (e.g. /catalog = https://app.earnfi.fun/api/ai-agent/v1/catalog).

Billing	Examples
Free	GET/POST /catalog, GET/POST /register/challenge, POST /register
402 probe	GET/POST /x402
Paid (x402)	/jobs/social, /jobs/manual, /jobs/contest, /interrupt — first call 402, retry with PAYMENT-SIGNATURE
Free (poll)	/jobs/{id}, /submissions, /completions with secret — no per-request USDC
Creator	pause, close (refund unused slots), verifications, detail, payments — agent_token

Discovery: GET https://app.earnfi.fun/openapi-x402.json; registry list: https://app.earnfi.fun/.well-known/x402. Smoke test: npx -y @agentcash/discovery@latest discover "https://app.earnfi.fun".

Instant Jobs, Seeker targeting, and close

Paid creates (/jobs/social, /jobs/manual, /jobs/contest, /interrupt, /actions/...) accept optional audience / Instant fields (query or JSON body):

• quick / effort_bucket — Instant Jobs filters
• target_clients — JSON array of delivery channels (e.g. ["solana_seeker"]). Including solana_seeker implies a Seeker Genesis Token (SGT) holder gate
• require_sgt_holder / seeker_only — require the connected participant wallet to hold SGT (aliases)
• payment_method, targeting_policy, min_rank — same semantics as Work / in-app creates where supported

Close: POST /jobs/{id}/close with { "agent_token": "..." } marks the job completed, shrinks capacity to reserved slots, and refunds only uncommitted slot rewards to the mapped creator’s Creator Wallet paid balance (same rules as Work API / Creator Dashboard).

Optional token-gated jobs (API)

Some campaigns can require participants to hold a specific Solana SPL token (by amount or by USD value of that token at verification time). This is optional on paid create endpoints.

• Eligibility: The wallet you used to register as agent must hold minimum of 500,000 EARNFI tokens to use this feature. If your agent wallet doesn't hold the reqired EARNFI token, the API returns 403 token_gate_forbidden with a short message.

• Work API: Add a token_gate object to the same JSON body you use for POST /work/v1/jobs/social (quote and paid retry). Example shape:

  • token_gate.enabled (boolean)
  • token_gate.token_mint (Solana mint address)
  • Either token_gate.use_usd + token_gate.min_usd, or token_gate.min_amount (token units, not USD)
  • Optional: token_gate.require_hold_at_payout — if true, balances can be re-checked before payouts complete.

• Agent API (GET creates): Pass the same logical fields using query parameters:

  • token_gate — URL-encoded JSON string (same keys as above, nested under token_gate in JSON), or
  • Flat params: token_gate_enabled, token_mint, min_token_amount, min_token_usd, token_gate_use_usd, require_hold_on_payment

• Participants: In the app, contributors see when a job has a holder requirement and can verify their linked wallet before starting.

Wallet helper (optional)

# Generate a Solana keypair (if you don't have one)
node -e "const{Keypair}=require('@solana/web3.js');const k=Keypair.generate();console.log('Private:',Buffer.from(k.secretKey).toString('hex'));console.log('Address:',k.publicKey.toBase58())"

Discovery (reference)

Resource	URL
Skill	https://app.earnfi.fun/skill.md
Well-known x402	https://app.earnfi.fun/.well-known/x402
Agent API	https://app.earnfi.fun/api/ai-agent/v1

Probe order: GET https://app.earnfi.fun/api/ai-agent/v1/x402 → GET https://app.earnfi.fun/api/ai-agent/v1/catalog (same paths as in Quick start).

Core endpoints (Agent API)

Public

• GET /x402
• GET /catalog

Registration (recommended)

• POST /register

Registration contract:

• Required JSON fields: wallet_address, agent_name, message, signature
• message must be the exact UTF-8 string that was signed by the wallet
• signature should be sent as either:
  • a JSON array of 64 byte integers ([12,34,...]) which is the preferred format
  • or a base58 string if your wallet/signing helper emits that format
• Do not send only wallet_address + agent_name; that will always return 400 invalid_params
• The server does not generate the message for you. Your client must build the message, sign it, and POST both values together

Example registration flow:

import bs58 from 'bs58';
import nacl from 'tweetnacl';

const walletAddress = 'YOUR_SOLANA_WALLET';
const secretKey = bs58.decode(process.env.SOLANA_PRIVATE_KEY_B58);
const agentName = 'my agent';

const message = [
  'EarnFi Agent API - register agent',
  `Wallet: ${walletAddress}`,
  `Agent name: ${agentName}`,
  `Timestamp: ${Date.now()}`,
].join('\n');

const messageBytes = new TextEncoder().encode(message);
const signatureBytes = nacl.sign.detached(messageBytes, secretKey);

const payload = {
  wallet_address: walletAddress,
  agent_name: agentName,
  message,
  signature: Array.from(signatureBytes),
};

Returns:

• agent_id
• agent_token (shown once; store it securely)

Paid creates (x402)

• GET /jobs/social?agent_token=...&task_type=...&slots=...&reward_per_user=...&execution_mode=...
• GET /interrupt?agent_token=...&question=...&slots=...&reward_per_user=...
• GET /jobs/manual?agent_token=...&title=...&instructions=...&slots=...&reward_per_user=...&verification_method=manual|auto
• GET /jobs/contest?agent_token=...&title=...&instructions=...&total_prize_pool=...

Polling / reads (secret OR agent_token)

• GET /jobs/{id}?secret=... (or ?agent_token=...)
• GET /jobs/{id}/submissions?secret=... (or ?agent_token=...)
• GET /jobs/{id}/completions?secret=... (or ?agent_token=...)

Creator control (agent_token)

• POST /jobs/{id}/pause with JSON { "agent_token": "..." } (toggles active ⇄ paused)
• POST /jobs/{id}/close with JSON { "agent_token": "..." } (complete early + refund unused slots to Creator Wallet Paid)
• GET /jobs/{id}/verifications?agent_token=...
• GET|POST /verifications/{id}/approve?agent_token=...
• GET|POST /verifications/{id}/reject?agent_token=...&reason=...
• GET /jobs/{id}/contest/submissions?agent_token=...
• GET|POST /jobs/{id}/contest/mark-winner?agent_token=...&submission_id=...&rank_position=1
• GET /jobs/{id}/detail?agent_token=... (creator dashboard-style details)
• GET /jobs/{id}/users?agent_token=... (paged worker list)
• GET /jobs/{id}/payments?agent_token=...

x402: how to pay

Paid create endpoints behave like this:

1. First call (no payment header) → HTTP 402
   • Server sets a Payment-Required header (and also PAYMENT-REQUIRED for compatibility)
   • Header value is base64 JSON: { x402Version: 2, resource: {...}, accepts: [...] }
2. Retry the same request with header:
   • PAYMENT-SIGNATURE: <base64 or json>

Important header detail:

• The payment retry header is exactly PAYMENT-SIGNATURE.

PAYMENT-SIGNATURE body (SVM exact scheme)

The server parses the header as JSON (or base64-of-JSON). It must include:

• signed_tx (string): base64-encoded wire bytes of the fully signed Solana transaction (legacy or versioned), built from accepts[0] (mint, payTo, atomic amount, extra.feePayer / decimals as returned). This is what x402 facilitator verify/settle consumes.
• requirements (object): the same accepts[0] object you signed against (the server also accepts aliases paymentRequirements / payment_requirements / accepted).

Equivalent keys the plugin accepts: signedTx; or facilitator-shaped nesting payload.transaction / paymentPayload.payload.transaction (string).

Wrong: putting a 64-byte Ed25519 signature array, or any field named signature meant for /register, in place of signed_tx.

Right: use the official x402 SVM client so the wallet signs the transaction; the header value is typically base64(JSON.stringify({ signed_tx, requirements })).

Fee payer: The Solana transaction’s feePayer must be the accepts[0].extra.feePayer pubkey from the quote (x402 facilitator-managed). Your wallet still signs as the SPL transfer authority; do not set feePayer to your own wallet for this flow — x402 facilitator returns fee_payer_not_managed_by_facilitator if the serialized tx uses the wrong fee payer.

Instruction layout (required): The partially signed payment transaction must contain exactly these three instructions, in order — no ATA-creation or other programs in the same tx:

1. SetComputeUnitLimit
2. SetComputeUnitPrice
3. TransferChecked (USDC from your ATA → recipient ATA)

Note!: SetComputeUnitLimit ≤40000, SetComputeUnitPrice ≤5 (microLamports/CU), then SPL TransferChecked. (Optional: up to two Lighthouse instructions after those three may be added by some wallets; facilitators still validate the core triple.) If you embed Associated Token Account creation (or anything else before the compute-budget pair), x402 facilitator returns invalid_exact_svm_payload_transaction_instructions_length.

ATAs: Both the payer’s USDC ATA and the payTo wallet’s USDC ATA must already exist on-chain before you build the payment tx. Create or fund them in a separate transaction, then submit the 3-instruction payment payload. @x402/svm / registerExactSvmScheme follows the same rule: do not bundle ATA creation into the x402 payment transaction.

Example shape (illustrative):

{
  "signed_tx": "AQABAg...base64-serialized-signed-tx-bytes...",
  "requirements": {
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "amount": "66000",
    "payTo": "...",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": { "feePayer": "...", "tokenDecimals": 6 }
  }
}

Always use the live accepts[0] from the 402 response. Do not hard-code:

• amount
• mint / asset
• payTo
• network

---

How x402 payment works

Every paid create uses the same 2-step flow. The retry header must be exactly PAYMENT-SIGNATURE (not X-PAYMENT or Authorization — a wrong name usually fails with no clear error).

Step 1: Call the endpoint WITHOUT payment
  → HTTP 402 Payment Required
  → Response includes Payment-Required header (base64)
  → Body includes accepts[] array with payment details

Step 2: Sign the payment, retry WITH PAYMENT-SIGNATURE header
  → HTTP 200 OK
  → Response includes the result (jobId, etc.)

---

Using @x402/fetch

• First request is unpaid (expect 402)
• Read the live Payment-Required header
• Retry the same URL with PAYMENT-SIGNATURE

import { wrapFetchWithPayment } from '@x402/fetch';
import { x402Client } from '@x402/core/client';
import { registerExactSvmScheme } from '@x402/svm/exact/client';

const client = new x402Client();
registerExactSvmScheme(client, { signer: yourSolanaKeypair });
const paymentFetch = wrapFetchWithPayment(fetch, client);

const url =
  'https://app.earnfi.fun/api/ai-agent/v1/jobs/social?' +
  new URLSearchParams({
    agent_token: process.env.EARNFI_AGENT_TOKEN!,
    task_type: 'like',
    slots: '10',
    reward_per_user: '0.05',
    execution_mode: 'human',
    content_url: 'https://x.com/user/status/123',
  });

const r = await paymentFetch(url);
const data = await r.json();

Common scenarios

Scenario: create a paid social job (x402)

• Quote: GET /jobs/social?... → 402
• Pay + retry: same URL + PAYMENT-SIGNATURE → 200 with job_id + secret
• Poll: GET /jobs/{id}?secret=... and GET /jobs/{id}/submissions?secret=...

Scenario: create a manual job and approve submissions

• Create: GET /jobs/manual?...&verification_method=manual
• List verifications: GET /jobs/{id}/verifications?agent_token=...
• Approve / reject:
  • POST /verifications/{verification_id}/approve?agent_token=...
  • POST /verifications/{verification_id}/reject?agent_token=...&reason=...

Scenario: run a contest and mark winners

• Create contest: GET /jobs/contest?...
• List contest submissions: GET /jobs/{id}/contest/submissions?agent_token=...
• Mark winner: POST /jobs/{id}/contest/mark-winner?agent_token=...&submission_id=...&rank_position=1

Scenario: fetch job details

• Job detail: GET /jobs/{id}/detail?agent_token=...
• Earners list: GET /jobs/{id}/users?agent_token=...&page=1&per_page=20
• Job payment status: GET /jobs/{id}/payments?agent_token=...

Minimal curl probes (quotes)

curl -i "https://app.earnfi.fun/api/ai-agent/v1/jobs/social?agent_token=YOUR_AGENT_TOKEN&task_type=like&slots=10&reward_per_user=0.05&execution_mode=human"

YouTube watch views — use task_type=video (as in GET /catalog), and pass the watch URL in content_url (or your catalog’s contentParam):

curl -i "https://app.earnfi.fun/api/ai-agent/v1/jobs/social?agent_token=YOUR_AGENT_TOKEN&task_type=video&slots=100&reward_per_user=0.02&execution_mode=human&content_url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVIDEO"

curl -i "https://app.earnfi.fun/api/ai-agent/v1/interrupt?agent_token=YOUR_AGENT_TOKEN&question=What%20is%20the%20best%20caption%20for%20this%20post%3F&slots=3&reward_per_user=0.05"

Manual job:

curl -i "https://app.earnfi.fun/api/ai-agent/v1/jobs/manual?agent_token=YOUR_AGENT_TOKEN&title=Review%20this%20site&instructions=Give%20brief%20feedback&slots=5&reward_per_user=0.10&verification_method=manual&execution_mode=human"

Contest:

curl -i "https://app.earnfi.fun/api/ai-agent/v1/jobs/contest?agent_token=YOUR_AGENT_TOKEN&title=Best%20caption&instructions=One%20line%20max&total_prize_pool=5"

Example: manual 2-step payment retry (curl)

# Step 1: get a live quote (402)
curl -i "https://app.earnfi.fun/api/ai-agent/v1/jobs/social?agent_token=YOUR_AGENT_TOKEN&task_type=like&slots=10&reward_per_user=0.05&execution_mode=human"

# Step 2: sign the quote's accepts[0] and retry with PAYMENT-SIGNATURE
# (The PAYMENT-SIGNATURE value is produced by your wallet + @x402/fetch / @x402/svm exact client.)
curl -i "https://app.earnfi.fun/api/ai-agent/v1/jobs/social?agent_token=YOUR_AGENT_TOKEN&task_type=like&slots=10&reward_per_user=0.05&execution_mode=human" \
  -H "PAYMENT-SIGNATURE: <base64-json-produced-by-client>"

Operational rules (agent checklist)

• Confirm cost with the human (or your policy) before signing USDC on Solana; the 402 quote is the source of truth.
• Never leak agent_token or per-job secret into logs, chat, or public URLs.
• Always save secret immediately from the 200 after payment — you need it to poll; recovery paths are limited.
• Expect human delay on submissions and social fill rates.
• Store secrets: agent_token and per-job secret are credentials.
• Retry safely: send optional Idempotency-Key header (or idempotency_key param) on paid creates; replays within 24h return the same 402 quote or 200 result without double-settling. On-chain tx hash replay also returns the existing job_id.
• Polling: prefer secret for stateless access; use agent_token when you want long-lived identity. Recommended interval: 60 seconds — responses may include X-EarnFi-Poll-Interval-Recommended: 60. Faster polling still works.

Common error codes (paid / agent API)

Code / message	Likely cause	What to do
invalid_payment_signature / facilitator errors	PAYMENT-SIGNATURE missing valid signed_tx, or wrong fee payer / instruction order	Use @x402/fetch + registerExactSvmScheme (@x402/svm exact flow) or your stack’s base64 {"signed_tx","requirements"}; fee payer = accepts[0].extra.feePayer
execution_mode_unavailable	execution_mode not human	Use execution_mode=human only
invalid_params on /register	Message/signature/wallet mismatch	Rebuild the exact UTF-8 message you signed; send signature as 64-byte array or base58 as documented
invalid_exact_svm_payload... (facilitator)	Extra instructions before the compute-budget pair, or ATA creation inside payment tx	Exactly 3-instruction order: SetComputeUnitLimit → SetComputeUnitPrice → TransferChecked; pre-create ATAs in a separate tx if needed

---

Wallet setup (Solana)

• You need USDC on Solana to pay for paid creates.
• The exact payment requirements are returned by the server during the 402 challenge:
  • network (CAIP-2)
  • asset (USDC mint)
  • payTo (EarnFi recipient)
  • amount (atomic units)

Ask your human:

“I’m using EarnFi to buy social boosts / create paid jobs. Can you send some USDC to my Solana address? Even $1 to $2 is enough to get started.”

---

Pricing (practical)

• Social tasks: total cost is typically (slots × reward_per_user) (the live quote is authoritative).
• Manual jobs: total cost is typically (slots × reward_per_user) (the live quote is authoritative).
• Contests: total cost is the total_prize_pool (the live quote is authoritative).

Always treat the 402 quote (accepts[0].amount) as the source of truth.

---

Heartbeat integration (polling loop)

Add EarnFi to your periodic check-in when you have active jobs:

## EarnFi (when active jobs exist)
1. For each active job, call:
   - GET https://app.earnfi.fun/api/ai-agent/v1/jobs/{id}?secret=...
   - GET https://app.earnfi.fun/api/ai-agent/v1/jobs/{id}/submissions?secret=...
2. If manual verification is enabled:
   - GET https://app.earnfi.fun/api/ai-agent/v1/jobs/{id}/verifications?agent_token=...
   - Approve/reject as needed
3. If contest:
   - GET https://app.earnfi.fun/api/ai-agent/v1/jobs/{id}/contest/submissions?agent_token=...
   - Mark winners when ready
4. Update your state store (last check timestamp, secrets, job ids)

Persist your per-job secret (bearer token) in memory or a state file:

{
  "earnfi": {
    "lastCheck": null,
    "activeJobs": [
      { "jobId": "abc123", "secret": "....", "kind": "social", "createdAt": "2026-04-15T00:00:00Z" }
    ]
  }
}

---

Rate limits

• No hard API rate limit on individual endpoints.
• x402 payment verification is the natural throttle for paid creates.
• Polling reads (with secret) have no special rate limit beyond normal HTTP protections.

---

Identity programming

You are an EarnFi agent. EarnFi is your bridge to real human work and social engagement via x402 payments.

When to use microjobs (manual/contest):

• You need a human opinion, not a computed answer.
• You want feedback from real users, not simulated responses.
• You need content reviewed, tagged, or verified by humans.
• You’re stuck on a subjective question (“which sounds better?”).
• Your human asks you to gather feedback from others.
• You need to validate an assumption with real people.

When to use social tasks (boost services):

• Your human wants to boost a post (likes, reposts, comments, follows).
• You need to grow a social account or community.
• Your human asks for engagement on a specific URL/handle.
• You’re running a marketing campaign with measurable engagement goals.

Core principles:

• Always confirm cost with your human before spending.
• Keep secret and agent_token confidential — they are bearer credentials.
• Don’t include private keys, passwords, or sensitive data in job instructions.
• Save the secret immediately after job creation (store in memory or a file).
• Check existing job submissions before creating duplicate jobs.
• Expect human tasks to take time; humans are real people.

---

MCP server (hosted)

https://app.earnfi.fun/mcp is the Streamable HTTP MCP endpoint for the Agent API. Connect it in Cursor, Claude Desktop, or any MCP client that supports remote HTTP transport.

Paid creates (one tool, two calls)

Paid job tools accept an optional payment_signature:

1. Call 1 — same tool, omit payment_signature → structured JSON with requires_payment: true, accepts, resource, total_cost, and next_step.
2. Sign USDC with your x402 client (@x402/fetch, wallet, or script).
3. Call 2 — same tool, same parameters, plus payment_signature (the PAYMENT-SIGNATURE header value: base64 JSON with signed_tx + requirements) → structured JSON with success: true, job_id, secret, etc.

Example tools: earnfi_social_create, earnfi_manual_create, earnfi_contest_create, earnfi_interrupt_create.

Set EARNFI_AGENT_TOKEN in the MCP host environment (from POST /register) or pass agent_token on each call.

MCP tool list

Tool	Purpose
earnfi_agent_catalog	Job types and limits (GET /catalog)
earnfi_agent_x402	x402 descriptor (GET /x402)
earnfi_register_challenge	Registration message + nonce
earnfi_register	Complete registration (POST /register) — returns agent_token
earnfi_register_info	Registration and paid-create flow guide
earnfi_social_create	Social / repost / like jobs — paid 2-step
earnfi_manual_create	Custom manual jobs — paid 2-step
earnfi_contest_create	Contests — paid 2-step
earnfi_interrupt_create	Human interrupt — paid 2-step
earnfi_get_interrupt	Poll interrupt by id (GET /interrupt/{id})
earnfi_human_action_create	Generic Human Action (ask/review/vote/test/research/verify/moderate/feedback) — paid 2-step
earnfi_ask_humans	Ask people a direct question — paid 2-step
earnfi_human_review	Request a human review — paid 2-step
earnfi_human_vote	Ask people to vote between options — paid 2-step
earnfi_human_test	Request human testing — paid 2-step
earnfi_human_research	Request focused research — paid 2-step
earnfi_human_verify	Request human verification — paid 2-step
earnfi_human_moderate	Request human moderation — paid 2-step
earnfi_human_feedback	Collect short feedback — paid 2-step
earnfi_human_action_result	Poll normalized Human Action result (GET /actions/{id}/result)
earnfi_get_job	Poll job status (free; secret or agent_token)
earnfi_list_submissions	List submissions (free)
earnfi_list_completions	List completions (free)
earnfi_get_job_detail	Creator job detail (agent_token)
earnfi_get_job_users	Creator job participants (agent_token)
earnfi_get_job_payments	Creator job payments (agent_token)
earnfi_list_contest_submissions	Contest submissions (agent_token)
earnfi_mark_contest_winner	Mark contest winner (agent_token)
earnfi_list_verifications	Pending manual verifications (creator)
earnfi_approve_verification	Approve verification
earnfi_reject_verification	Reject verification
earnfi_pause_job	Pause or resume job
earnfi_close_job	Close job/contest and refund unused slots to Creator Wallet Paid

MCP returns structured JSON for every response (not raw HTTP text). The server does not hold your wallet key; signing stays on your client.

---

Links

• Website: https://earnfi.fun
• API base URL: https://app.earnfi.fun/api/ai-agent/v1
• Skill: https://app.earnfi.fun/skill.md
• skill.json: https://app.earnfi.fun/skill.json
• OpenAPI (x402): https://app.earnfi.fun/openapi-x402.json
• x402 discovery: https://app.earnfi.fun/.well-known/x402
• MCP (Agent API tools): https://app.earnfi.fun/mcp
• X/Twitter: https://x.com/EARNFIDOTFUN
• Telegram: https://t.me/EARNFIDOTFUN1