Searching Algorand Examples

Find working contract examples and code patterns from Algorand Foundation repositories using GitHub tools.

Overview / Core Workflow

1. •Identify what pattern or example the user needs
2. •Choose the appropriate tool (github_search_code, github_get_file_contents, or github_search_repositories)
3. •Search priority repositories first (devportal-code-examples, puya-ts)
4. •Retrieve the relevant file(s)
5. •Also fetch corresponding test files when applicable

How to proceed

1. •

   Determine the search type:

   • •Looking for a specific pattern → use github_search_code
   • •Need a specific file → use github_get_file_contents
   • •Discovering repositories → use github_search_repositories
2. •

   Search priority repositories first:

   Priority	Repository	Best For
   1	algorandfoundation/devportal-code-examples	Beginner-friendly patterns
   2	algorandfoundation/puya-ts	Advanced TypeScript examples
   3	algorandfoundation/puya	Python examples
   4	algorandfoundation/algokit-*	Templates and utilities

3. •

   Execute the search:

   code

   # Search for code patterns
   github_search_code query:"BoxMap org:algorandfoundation language:typescript"
   
   # Get specific file
   github_get_file_contents owner:algorandfoundation repo:puya-ts path:examples/voting/contract.algo.ts
   
   # List directory contents
   github_get_file_contents owner:algorandfoundation repo:puya-ts path:examples
   
   # Find repositories
   github_search_repositories query:"topic:algorand smart-contract"
   

4. •

   Always fetch test files:

   • •For any contract file, check for corresponding *.spec.ts or *_test.py
   • •Tests show how to call methods and verify behavior

Important Rules / Guidelines

• •Search algorandfoundation first — Official repos have vetted, up-to-date examples
• •Always include test files — They demonstrate correct usage patterns
• •Use specific queries — Include org:algorandfoundation and language:typescript for better results
• •Check file paths in devportal-code-examples:
  • •TypeScript: projects/typescript-examples/contracts/
  • •Python: projects/python-examples/contracts/
• •Prefer puya-ts/examples for complex patterns — Voting, AMM, auction examples are comprehensive

If GitHub MCP Tools Unavailable

Use web search as fallback:

• •For code search: site:github.com algorandfoundation {pattern} language:typescript
• •For specific files: Browse directly to https://github.com/algorandfoundation/puya-ts/tree/main/examples
• •For repos: Search site:github.com algorand {topic}

Key URLs to browse directly:

• •https://github.com/algorandfoundation/devportal-code-examples
• •https://github.com/algorandfoundation/puya-ts/tree/main/examples
• •https://github.com/algorandfoundation/puya/tree/main/examples

Common Variations / Edge Cases

References / Further Reading

• •Tool Reference
• •DevPortal Code Examples
• •Puya TypeScript Examples
• •Algorand Developer Portal