Neynar Onchain API

openapi: 3.0.4
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: The Neynar API allows you to interact with the Farcaster protocol among other things. See the [Neynar docs](https://docs.neynar.com/reference) for more details.
  title: Neynar Action Onchain API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- description: Operations related to onchain data
  name: Onchain
paths:
  /v2/farcaster/fungible/owner/relevant/:
    get:
      description: Fetch a list of relevant owners for a on chain asset. If a viewer is provided, only relevant holders will be shown. This usually shows on a fungible asset page as "X, Y, Z and N others you know own this asset".
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-relevant-fungible-owners
      operationId: fetch-relevant-fungible-owners
      parameters:
      - description: Contract address of the fungible asset (Ethereum or Solana)
        in: query
        name: contract_address
        required: true
        schema:
          example: 0x0db510e79909666d6dec7f5e49370838c16d950f (eth) --OR-- EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v (solana)
          type: string
      - description: Network of the fungible asset.
        in: query
        name: network
        required: true
        schema:
          enum:
          - ethereum
          - optimism
          - base
          - arbitrum
          - solana
          title: FungibleOwnerRelevantNetwork
          type: string
      - description: If you provide a viewer_fid, the response will include token holders from the user's network, respecting their mutes and blocks and including viewer_context; if not provided, the response will show top token holders across the network—both sets can be combined to generate a longer list if desired.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelevantFungibleOwnersResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: Relevant owners
      tags:
      - Onchain
  /v2/farcaster/fungible/owner/relevant/bulk:
    get:
      description: Fetch relevant owners for multiple on chain assets in a single request, up to 10 contract addresses at a time.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-bulk-relevant-fungible-owners
      operationId: fetch-bulk-relevant-fungible-owners
      parameters:
      - description: Comma separated list of contract addresses, up to 10 at a time
        in: query
        name: contract_addresses
        required: true
        schema:
          example: 0x0db510e79909666d6dec7f5e49370838c16d950f,0x4ed4e862860bed51a9570b96d89af5e1b0efefed
          type: string
          x-comma-separated: true
      - description: Network of the fungible assets.
        in: query
        name: network
        required: true
        schema:
          enum:
          - ethereum
          - optimism
          - base
          - arbitrum
          - solana
          type: string
      - description: If you provide a viewer_fid, the response will include token holders from the user's network, respecting their mutes and blocks and including viewer_context.
        in: query
        name: viewer_fid
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkRelevantFungibleOwnersResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: Bulk relevant owners
      tags:
      - Onchain
  /v2/farcaster/fungible/send/:
    post:
      description: Send fungibles in bulk to several farcaster users. A funded wallet is to required use this API. React out to us on the Neynar channel on farcaster to get your wallet address.
      externalDocs:
        url: https://docs.neynar.com/reference/send-fungibles-to-users
      operationId: send-fungibles-to-users
      parameters:
      - $ref: '#/components/parameters/WalletIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionSendFungiblesReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionSendFungiblesResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Send fungibles
      tags:
      - Onchain
  /v2/farcaster/fungible/trades/:
    get:
      description: Get recent trades for a specific fungible within a timeframe. Returns trades ordered by timestamp (most recent first).
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-fungible-trades
      operationId: fetch-fungible-trades
      parameters:
      - in: query
        name: network
        required: true
        schema:
          enum:
          - base
          type: string
      - description: Contract address
        in: query
        name: address
        required: true
        schema:
          type: string
      - description: Time window for trades e.g. "1h", "6h", "12h", "24h", "7d"
        in: query
        name: time_window
        schema:
          default: 24h
          enum:
          - 1h
          - 6h
          - 12h
          - 24h
          - 7d
          type: string
      - description: Minimum USD amount to filter trades
        in: query
        name: min_amount_usd
        schema:
          type: number
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  object:
                    enum:
                    - fungible_trades
                    type: string
                  trades:
                    items:
                      properties:
                        object:
                          enum:
                          - trade
                          type: string
                        pool:
                          properties:
                            address:
                              type: string
                            object:
                              enum:
                              - pool
                              type: string
                            protocol_family:
                              type: string
                            protocol_version:
                              type: string
                          required:
                          - object
                          - address
                          type: object
                        trader:
                          $ref: '#/components/schemas/UserDehydrated'
                        transaction:
                          properties:
                            hash:
                              type: string
                            net_transfer:
                              properties:
                                object:
                                  enum:
                                  - net_transfer
                                  type: string
                                receiving_fungible:
                                  $ref: '#/components/schemas/FungibleBalance'
                                sending_fungible:
                                  $ref: '#/components/schemas/FungibleBalance'
                              required:
                              - object
                              - receiving_fungible
                              - sending_fungible
                              type: object
                            network:
                              properties:
                                name:
                                  type: string
                                object:
                                  enum:
                                  - network
                                  type: string
                              required:
                              - object
                              - name
                              type: object
                          required:
                          - hash
                          - network
                          - net_transfer
                          type: object
                      required:
                      - object
                      - trader
                      - transaction
                      type: object
                    type: array
                required:
                - object
                - trades
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Get fungible trades
      tags:
      - Onchain
  /v2/farcaster/fungible/trending/:
    get:
      description: Fetch trending fungibles based on buy activity from watched addresses. Returns fungibles ranked by USD buy volume and buy count within the specified time window.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-trending-fungibles
      operationId: fetch-trending-fungibles
      parameters:
      - in: query
        name: network
        required: true
        schema:
          enum:
          - base
          type: string
      - description: Time window for trending calculations e.g. "1h", "6h", "12h", "24h", "7d"
        in: query
        name: time_window
        schema:
          default: 24h
          enum:
          - 1h
          - 6h
          - 12h
          - 24h
          - 7d
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  trending:
                    items:
                      properties:
                        fungible:
                          properties:
                            address:
                              description: The contract address of the token
                              type: string
                            decimals:
                              description: The number of decimals the token uses
                              type: integer
                            logo:
                              description: The logo URL of the token
                              nullable: true
                              type: string
                            name:
                              description: The token name e.g. "Ethereum"
                              type: string
                            network:
                              $ref: '#/components/schemas/Network'
                            object:
                              enum:
                              - fungible
                              type: string
                            price:
                              properties:
                                in_usd:
                                  type: string
                              required:
                              - in_usd
                              type: object
                            symbol:
                              description: The token symbol e.g. "ETH"
                              type: string
                            total_supply:
                              description: The total supply of the token
                              nullable: true
                              type: string
                          required:
                          - object
                          - network
                          - name
                          - symbol
                          - address
                          - decimals
                          - total_supply
                          - logo
                          type: object
                        object:
                          enum:
                          - trending_fungible
                          type: string
                      required:
                      - object
                      - fungible
                      type: object
                    type: array
                required:
                - trending
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Trending fungibles
      tags:
      - Onchain
  /v2/farcaster/fungibles/:
    get:
      description: Fetch details for fungible assets identified by fungible identifiers.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-fungibles
      operationId: fetch-fungibles
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: Comma-separated fungible identifiers
        in: query
        name: fungibles
        required: true
        schema:
          example: eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913,eip155:8453/erc20:0x2f6c17fa9f9bc3600346ab4e48c0701e1d5962ae
          type: string
      - description: Optional FID of the viewer to personalize cast count filtering
        in: query
        name: viewer_fid
        schema:
          type: number
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FungiblesResponseSchema'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Fetch fungibles
      tags:
      - Onchain
  /v2/farcaster/nft/deploy/erc721/:
    post:
      description: Deploy a new ERC-721A (series) NFT collection.
      externalDocs:
        url: https://docs.neynar.com/reference/deploy-erc721
      operationId: deploy-erc721
      parameters:
      - $ref: '#/components/parameters/WalletIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                external_link:
                  type: string
                image:
                  type: string
                max_supply:
                  default: 0
                  description: Max supply (0 = unlimited)
                  maximum: 281474976710655
                  minimum: 0
                  type: integer
                mint_config:
                  properties:
                    end_timestamp:
                      description: Unix timestamp (defaults to no end date)
                      maximum: 281474976710655
                      minimum: 0
                      type: integer
                    max_per_tx:
                      default: 0
                      description: Max tokens per transaction (0 = unlimited)
                      maximum: 281474976710655
                      minimum: 0
                      type: integer
                    max_per_wallet:
                      default: 0
                      description: Max tokens per wallet (0 = unlimited)
                      maximum: 281474976710655
                      minimum: 0
                      type: integer
                    price_per_token:
                      default: '0'
                      description: Price per token in wei (0 = free mint)
                      pattern: ^\d{1,57}$
                      type: string
                    start_timestamp:
                      description: Unix timestamp (defaults to current time)
                      maximum: 281474976710655
                      minimum: 0
                      type: integer
                  type: object
                name:
                  maxLength: 255
                  minLength: 1
                  type: string
                network:
                  enum:
                  - base
                  - optimism
                  - base-sepolia
                  type: string
                royalty_bps:
                  default: 0
                  description: Royalty in basis points (500 = 5%, max 2500 = 25%)
                  maximum: 2500
                  minimum: 0
                  type: integer
                royalty_recipient:
                  description: Defaults to creator wallet
                  example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
                  pattern: ^0x[a-fA-F0-9]{40}$
                  type: string
                symbol:
                  maxLength: 32
                  minLength: 1
                  type: string
              required:
              - network
              - name
              - symbol
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  collection:
                    properties:
                      address:
                        $ref: '#/components/schemas/EthAddress'
                      name:
                        type: string
                      network:
                        enum:
                        - base
                        - optimism
                        - base-sepolia
                        type: string
                      symbol:
                        type: string
                      transaction_hash:
                        pattern: ^0x[a-fA-F0-9]{64}$
                        type: string
                      type:
                        enum:
                        - ERC721
                        type: string
                    required:
                    - type
                    - network
                    - address
                    - name
                    - symbol
                    - transaction_hash
                    type: object
                  object:
                    enum:
                    - nft_collection
                    type: string
                required:
                - object
                - collection
                type: object
          description: '201'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Deploy ERC-721 collection
      tags:
      - Onchain
  /v2/farcaster/nft/image/:
    post:
      description: Generate a new image or edit existing images using AI. Returns a publicly accessible URL to the generated image.
      externalDocs:
        url: https://docs.neynar.com/reference/generate-image
      operationId: generate-image
      parameters:
      - $ref: '#/components/parameters/WalletIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                format:
                  default: png
                  description: 'Output image format (default: png)'
                  enum:
                  - png
                  - jpeg
                  - webp
                  type: string
                height:
                  default: 1024
                  description: 'Output image height in pixels (default: 1024)'
                  maximum: 4096
                  minimum: 1
                  type: integer
                high_fidelity:
                  default: false
                  description: 'Use the high-fidelity model (slower but more detailed). Default: false.'
                  type: boolean
                prompt:
                  description: Text prompt describing the image to generate
                  minLength: 1
                  type: string
                source_image_urls:
                  description: Optional array of source image URLs to edit or use as reference (max 5)
                  items:
                    format: uri
                    type: string
                  maxItems: 5
                  type: array
                width:
                  default: 1024
                  description: 'Output image width in pixels (default: 1024)'
                  maximum: 4096
                  minimum: 1
                  type: integer
              required:
              - prompt
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  image_url:
                    format: uri
                    type: string
                required:
                - image_url
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Generate an NFT image
      tags:
      - Onchain
  /v2/farcaster/nft/metadata/token:
    post:
      description: Uploads metadata JSON to S3 for one or more tokens on a deployed contract. Requires contract ownership via the wallet header.
      externalDocs:
        url: https://docs.neynar.com/reference/upload-token-metadata
      operationId: upload-token-metadata
      parameters:
      - $ref: '#/components/parameters/WalletIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                contract_address:
                  description: Ethereum address
                  example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
                  pattern: ^0x[a-fA-F0-9]{40}$
                  title: EthAddress
                  type: string
                network:
                  enum:
                  - base
                  - optimism
                  - base-sepolia
                  type: string
                tokens:
                  items:
                    properties:
                      metadata:
                        properties:
                          animation_url:
                            type: string
                          attributes:
                            items:
                              properties:
                                display_type:
                                  enum:
                                  - number
                                  - boost_number
                                  - boost_percentage
                                  - date
                                  type: string
                                max_value:
                                  type: number
                                trait_type:
                                  type: string
                                value:
                                  oneOf:
                                  - type: string
                                  - type: number
                              required:
                              - trait_type
                              - value
                              type: object
                            type: array
                          background_color:
                            pattern: ^[0-9a-fA-F]{6}$
                            type: string
                          description:
                            type: string
                          external_url:
                            type: string
                          image:
                            type: string
                          name:
                            type: string
                          youtube_url:
                            type: string
                        required:
                        - name
                        - image
                        type: object
                      token_id:
                        type: string
                    required:
                    - token_id
                    - metadata
                    type: object
                  maxItems: 200
                  minItems: 1
                  type: array
              required:
              - network
              - contract_address
              - tokens
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  tokens:
                    items:
                      oneOf:
                      - properties:
                          token_id:
                            type: string
                          uri:
                            type: string
                        required:
                        - token_id
                        - uri
                        type: object
                      - properties:
                          error:
                            type: string
                          token_id:
                            type: string
                        required:
                        - token_id
                        - error
                        type: object
                    type: array
                required:
                - tokens
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZodError'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Upload NFT token metadata
      tags:
      - Onchain
  /v2/farcaster/nft/mint/:
    get:
      description: Simulates mint calldata for the given recipients, contract, and network. Useful for previewing calldata and ABI before minting.
      externalDocs:
        url: https://docs.neynar.com/reference/simulate-nft-mint
      operationId: simulate-nft-mint
      parameters:
      - description: JSON array of recipients (same structure as POST).
        in: query
        name: recipients
        required: true
        schema:
          type: string
      - description: Ethereum address
        in: query
        name: nft_contract_address
        required: true
        schema:
          example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
          pattern: ^0x[a-fA-F0-9]{40}$
          title: EthAddress
          type: string
      - description: Network to mint on.
        in: query
        name: network
        required: true
        schema:
          enum:
          - base
          - optimism
          - base-sepolia
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateNftMintResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZodError'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Simulate NFT mint calldata
      tags:
      - Onchain
    post:
      description: Mints an NFT to one or more recipients on a specified network and contract, using a configured server wallet. Contact us to set up your wallet configuration if you don't have one.
      externalDocs:
        url: https://docs.neynar.com/reference/mint-nft
      operationId: mint-nft
      parameters:
      - $ref: '#/components/parameters/WalletIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              description: Request body for NFT minting operation.
              properties:
                async:
                  description: If true, returns immediately after sending the transaction.
                  example: false
                  type: boolean
                contract_address:
                  description: Ethereum address
                  example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
                  pattern: ^0x[a-fA-F0-9]{40}$
                  title: EthAddress
                  type: string
                network:
                  description: Network to mint on.
                  enum:
                  - base
                  - optimism
                  - base-sepolia
                  example: base
                  type: string
                recipients:
                  description: List of recipients to mint to (1-200 recipients allowed).
                  items:
                    anyOf:
                    - properties:
                        address:
                          description: Ethereum address
                          example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
                          pattern: ^0x[a-fA-F0-9]{40}$
                          title: EthAddress
                          type: string
                        fid:
                          not: {}
                        quantity:
                          default: 1
                          description: Quantity to mint (must be at least 1). Defaults to 1.
                          example: 1
                          minimum: 1
                          type: integer
                      required:
                      - address
                      type: object
                    - properties:
                        address:
                          not: {}
                        fid:
                          description: The unique identifier of a

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/api-evangelist-neynar/refs/heads/main/openapi/neynar-onchain-api-openapi.yml