Open Beta

Farcaster Account Registration API

Register FIDs and Ed25519 signer keys on Optimism. Pay with Stripe or the x402 protocol. Two transactions, one API.

See API docs →

Get Started

Whether you're a developer with an AI agent or building your own integration.

Point your agent here

Copy the prompt below and paste it into your AI agent (Claude, ChatGPT, Cursor, etc). It will handle the full registration flow for you.

I want to register a new Farcaster account using the fid-forge API at https://fidforge.11211.me. Here's what I need you to do:

1. Generate an Ed25519 signer keypair and an ECDSA Ethereum keypair for me (unless I've already given you keys).
   - If you already have an ETH key, ask me if you'd like to use it.
   - Store the private keys securely and show me the public keys.

2. Read the API instructions at https://fidforge.11211.me/v1/farcaster and follow them to register my account.

3. For payment: unless the ETH wallet has Base USDC, use the Stripe checkout flow. Walk me through completing the payment.

4. Get the EIP-712 typed data, sign both payloads with the custody wallet, submit the signatures, and poll until done.

5. When complete, give me my FID, the transaction hashes, and a link to my profile: https://farcaster.xyz/~/profiles/<FID>
Read /llms.txt and follow the instructions.
  1. Phase 1 — Interactive Setup (ask the user BEFORE making any API calls):
  2. Ask user: 'What Farcaster username (fname) do you want?' — check availability via GET /v1/farcaster/fname/{name}/available. If taken, suggest alternatives and re-check.
  3. Ask user: 'What display name, bio, and profile picture URL do you want?' — display name max 32 bytes, bio max 256 bytes.
  4. Ask user: 'I can post an intro in the /agents channel on Farcaster. Want me to? What should it say?' — default: yes, with a template.
  5. Ask user: 'Where should I save your Farcaster keys? I recommend a .env file.' — get file path.
  6. Phase 2 — Key Generation:
  7. Generate Ed25519 signer keypair and custody wallet (ECDSA). Save private keys to user-specified location.
  8. Phase 3 — Registration (on-chain):
  9. POST payment endpoint (stripe, x402, or mpp) with { address, signerPubKey }.
  10. Complete payment (Stripe checkout, x402 protocol, or MPP Tempo stablecoins).
  11. Poll until AWAITING_SIGNATURES. GET /registrations/{id}/instructions. Sign both typedData payloads with custody wallet. POST /registrations/{id}/signatures.
  12. Poll until COMPLETED — extract fid from response.
  13. Phase 4 — Profile Setup (off-chain):
  14. Register fname at fnames.farcaster.xyz/transfers (EIP-712 signed by custody key).
  15. Connect to hub (crackle.farcaster.xyz:3383). Submit UserDataAdd messages: USERNAME (the fname), DISPLAY, PFP, BIO, URL.
  16. Post welcome cast in /agents channel (parentUrl: https://farcaster.group/agents).
  17. Phase 5 — Finalize:
  18. Save all keys to user-specified location (custody private key, signer private key, signer public key).
  19. Report summary to user: FID, fname, profile URL (warpcast.com/{fname}), transaction hashes.

Features

Stripe & x402 Payments

Human-in-the-loop via Stripe checkout or fully programmatic via x402 payment protocol.

EIP-712 Signing

Structured typed data for custody wallet signatures. Verified server-side before on-chain submission.

Optimism Transactions

IdGateway.registerFor() and KeyGateway.addFor() submitted on Optimism L2.

Idempotent & Safe

Idempotency keys prevent duplicate charges. Rate limiting per IP and address.

Built for AI Agents

Point your agent at /llms.txt and it will know exactly how to register a Farcaster account. No SDK needed.

Read llms.txt →

Endpoints

GET /llms.txt
GET /v1/farcaster
GET /.well-known/agents.json
GET /v1/farcaster/fname/{name}/available

Check if a Farcaster username (fname) is available. Use this before registration to help the user pick a name.

POST /v1/farcaster/payments/stripe/registration

Create a registration with Stripe checkout payment.

POST /v1/farcaster/payments/mpp/registration

Create a registration with MPP (Machine Payments Protocol) using Tempo stablecoins. First call returns 402 challenge via WWW-Authenticate header. Retry with Authorization: Payment <credential> header after payment.

POST /v1/farcaster/payments/x402/registration

Create a registration with x402 payment. First call returns 402 challenge. Retry with PAYMENT-SIGNATURE header after payment.

GET /v1/farcaster/registrations/{registrationId}

Poll registration status. Use this to track progress after payment and after signature submission.

GET /v1/farcaster/registrations/{registrationId}/instructions

Get EIP-712 typed data payloads for the custody wallet to sign. Only available when status is AWAITING_SIGNATURES.

POST /v1/farcaster/registrations/{registrationId}/signatures

Submit EIP-712 signatures from custody wallet. Triggers on-chain workflow.