CryptoPunks API

Complete REST API for accessing all 10,000 CryptoPunks, individual traits, and generating custom punk combinations with pixel-perfect rendering

Base URL: https://punks.art/api

💡 This API powers PunkMaker - Want to generate custom punks with a visual interface?Try the interactive app →

🙏 Building something cool? If you use this API in your app or project, a credit to punks.art would be awesome (but totally optional)! No strings attached - just spreading the punk love. ✨

GET /traits

Get all available traits with basic info (id, slug, category)

Query Parameters:

category - Filter by trait category (Background, Eyewear, etc.)
gender - Filter by gender (Male, Female, Unisex)
search - Search traits by name or category
limit - Limit number of results
offset - Offset for pagination
extended - Include extended traits (unisex versions of originally gender-specific traits like hoodie)
groupByCategory - Group results by category

Examples:

GET /api/traits?category=Hairstyle&gender=Female&limit=8

GET /api/traits?search=beard&limit=5

GET /api/traits?extended=true&category=Type

Sample Traits:

mohawkdark

regularshades

normalbeard

cigarette

earring

cowboyhat

tiara

wildhair

GET /traits/[slug]

Get data for a single trait or combine multiple traits using dash-separated slugs/IDs

Query Parameters:

format - Output format: json, pixels, svg, png, ascii, ansi (default: json)
size - Square size in pixels for PNG format (default: 24 or 32 for naked mode)
background - Solid color (red, ff0000), gradient (red-blue), or image URL (https://example.com/image.jpg)
ribbon - Add green corner ribbon overlay (PNG only, min size 48px): ribbon=yes

Examples:

GET /api/traits/mohawkdark

GET /api/traits/alien-regularshades-wildhair?format=svg&background=v1

GET /api/traits/male3-cowboyhat-normalbeard?format=png&size=256&background=v2

GET /api/traits/male3-cowboyhat?format=png&naked=yes&background=punk

GET /api/traits/cigarette?format=pixels

GET /api/traits/mohawkdark?format=ascii

GET /api/traits/mohawkdark?format=ansi

GET /api/traits/mohawkdark?format=png&size=64&ribbon=yes

Combination Examples:

alien + shades + hair

v1 (purple) bg

zombie + 3D glasses

v2 (classic) bg

female + tiara + earring

royalblue-lavender bg

male + cowboy + beard

orange-purple bg

GET /punks

Get list of all CryptoPunks with their token IDs and traits

Query Parameters:

limit - Limit number of results
offset - Offset for pagination
includeTraits=false - Exclude trait data for lighter response

Examples:

GET /api/punks?limit=15

GET /api/punks?offset=2500&limit=25

GET /api/punks?includeTraits=false&limit=100

Sample Punks:

#100

#500

#1000

#2113

#5000

#7804

#9999

GET /punks/[id]

Get specific CryptoPunk by token ID with multiple output formats

Query Parameters:

format - Output format: json, pixels, svg, png, ascii, ansi (default: json)
size - Square size in pixels for PNG format (default: 24 or 32 for naked mode)
background - Solid color (red, ff0000), gradient (red-blue), or image URL (https://example.com/image.jpg)
ribbon - Add green corner ribbon overlay (PNG only, min size 48px): ribbon=yes

Examples:

GET /api/punks/507

GET /api/punks/2113?format=svg&background=v1

GET /api/punks/8765?format=png&size=480&background=v2

GET /api/punks/2113?format=png&naked=yes&background=punk

GET /api/punks/42?format=pixels

GET /api/punks/2113?format=ascii

GET /api/punks/3466?format=ansi

GET /api/punks/2113?format=png&size=96&ribbon=yes

Response Format

All endpoints return JSON with a consistent structure:

{ "success": true, "data": { ... }, "total": 100, // For paginated results "count": 10 // For array results }

Background Colors & Gradients

Use the background parameter for solid colors, vertical gradients (multiple colors separated by dashes), or image URLs in PNG and SVG outputs. Images scale to cover the entire square while maintaining aspect ratio, with excess cropped out, and use pixelated rendering for crisp pixel art.

CSS Named Colors (147 total)

aliceblue, antiquewhite, aqua

crimson, cornflowerblue, coral

mediumseagreen, midnightblue

palevioletred, rebeccapurple

+ 139 more CSS colors

Hex Codes

ff0000 (red)

00ff00 (green)

0000ff (blue)

638696 (punk blue)

Presets

7 punk-specific presets

147 CSS named colors

Any hex color code

transparent (default)

See Complete Color Reference below ↓

Background Examples

background=red - Solid color background

background=red-blue - Simple two-color gradient

background=forsale - For sale brown preset

background=bids - Bids purple preset

background=wrapped1-wrapped2 - Wrapped green gradient

background=v1-forsale-bids - Three punk presets gradient

background=ff0000-00ff00-0000ff - RGB gradient with hex codes

background=https://example.com/bg.jpg - Image background with cover scaling and pixelated rendering

Visual Examples

Here are some examples of punks generated with different backgrounds and combinations, showcasing the punk-specific preset colors:

Punk #2113
Rainbow gradient

Punk #7804
forsale brown

Punk #3100
bids purple

Punk #8857
wrapped gradient

Custom combo
v1-forsale gradient

Custom combo
bids-wrapped1 gradient

Example URLs used above:

/api/punks/2113?format=png&background=5078C0-B081BC-E45197-E48384-FF8442-FFC54F

/api/punks/7804?format=png&background=forsale

/api/punks/3100?format=png&background=bids

/api/punks/8857?format=png&background=wrapped1-wrapped2

/api/traits/alien-regularshades-wildhair?format=png&background=v1-forsale

/api/traits/male3-cowboyhat-normalbeard?format=png&background=bids-wrapped1

Ribbon Overlays

Add a green corner ribbon overlay to PNG images using the ribbon parameter. This feature was originally created for "wrapped" punks as part of the CryptoPunks ecosystem lore, where wrapped punks displayed with a distinctive green ribbon indicator.

Simply add ribbon=yes to any PNG request to enable the green ribbon overlay. Requires PNG format and minimum 48px size.

Ribbon Examples

Punk #2113
with ribbon

Alien + Shades
with ribbon

Punk #7804
with ribbon

Zombie + 3D
with ribbon

ASCII & ANSI Text Art

Generate text-based pixel art representations of CryptoPunks using format=ascii (monochrome) or format=ansi (colored with ANSI escape codes).

ASCII Format

• Monochrome text art using Unicode characters

• ██ for black pixels (outlines)

• ░░ for darkest non-black color

• ▒▒ ▓▓ for other colors

• Skin pixels are invisible (spaces)

• Characters doubled horizontally for square proportions

ANSI Format

• Colored ASCII art with ANSI escape codes

• Same character mapping as ASCII

• Colors mapped to closest ANSI terminal colors

• Perfect for terminal display and Discord code blocks

• Copy-paste directly into terminals that support ANSI

Usage Tips

• ASCII: Copy into any text editor or chat application

• ANSI: Use in terminals, Discord code blocks, or ANSI-compatible viewers

• Best viewed with monospace fonts (Courier, Monaco, Consolas)

• Each punk pixel becomes 2 characters wide for better proportions

Complete Color Reference

All available colors for the background parameter, organized by category.

Punk-Specific Presets

Custom colors designed specifically for CryptoPunks theming:

punk

#638696

Classic punk blue

#A89CFF

Purple preset

#638696

Classic (same as punk)

forsale

#95554F

For sale brown

bids

#8E6FB6

Bids purple

wrapped1

#C8DFCA

Wrapped light green

wrapped2

#67A670

Wrapped dark green

CSS Named Colors (147 total)

All standard CSS color names are supported. Here are some popular examples:

red

blue

green

yellow

purple

orange

pink

cyan

magenta

lime

gold

silver

crimson

coral

indigo

violet

teal

navy

maroon

olive

Reds & Pinks

red, darkred, crimson, firebrick

pink, hotpink, deeppink, lightpink

indianred, lightcoral, salmon, tomato

Blues & Cyans

blue, darkblue, navy, midnightblue

cyan, darkcyan, lightcyan, aqua

skyblue, steelblue, cornflowerblue

Greens & Nature

green, darkgreen, forestgreen, lime

olive, olivedrab, yellowgreen

seagreen, mediumseagreen, springgreen

Complete list includes: All 147 CSS named colors including variations like lightblue, darkblue, mediumblue; lightgreen, darkgreen, mediumseagreen; purple, mediumpurple, rebeccapurple; and many more. See the W3Schools CSS Colors Reference for the complete list with visual examples.

Hex Colors

Use any 6-digit or 3-digit hex color code (with or without #):

ff0000 or #ff0000 → Red

00ff00 or #00ff00 → Green

0000ff or #0000ff → Blue

638696 or #638696 → Punk Blue

f0f or #f0f → Magenta (3-digit)

Usage Examples

background=punk → Classic punk blue

background=v1 → Purple preset

background=forsale → For sale brown

background=crimson → CSS crimson red

background=A89CFF → Custom hex purple

background=punk-white → Gradient from punk blue to white

background=v1-forsale-bids → Three-color gradient

Naked Mode

Add anatomically correct bodies to your punks using the naked parameter. Since CryptoPunks are normally just heads and necks, this feature expands the canvas from 24x24 to 32x32 pixels and generates a full naked body beneath the punk's head.

How it Works:

• Canvas Expansion: Expands from 24x24 to 32x32 pixels to accommodate the new body
• Body Generation: Creates a full naked body beneath the punk's head with matching skin tones
• Smart Clothing Removal: Removes clothing pixels from the head/neck area that would conflict with the naked body
• Scalable Output: size parameter still works for larger renders
• Full Compatibility: Works with all existing features - backgrounds, gradients, ribbons, and output formats

Parameters:

naked=yes (or true, 1) - Add a naked body to the punk (normally just head/neck)
dingdong=on (or yes, true, 1) - Add anatomical details, or tripod for variant
socks=on (or yes, true, 1) - Add gender-appropriate socks (requires naked=yes)

Examples:

GET /api/punks/2113?naked=yes&format=png&background=punk

GET /api/punks/507?naked=true&dingdong=on&format=png&size=128

GET /api/punks/2113?naked=yes&dingdong=tripod&socks=on&format=png&background=v1

GET /api/traits/female4-tiara?naked=yes&socks=true&format=png&size=256&background=forsale

GET /api/traits/male3-cowboyhat?naked=1&dingdong=tripod&format=svg&background=v1

Visual Examples:

Punk #2113
naked mode

Punk #507
with dingdong

Punk #2113
tripod variant

Punk #507
with socks

Female + Tiara
with socks

Punk #2113
tripod + socks

Technical Details

• Generated body colors automatically match the punk's skin tone from their Type trait

• Male and female punks have distinct anatomical differences and positioning

• Additional traits: normal dingdong, tripod variant, and gender-specific socks

• Trait-based layering system allows combining multiple body accessories

• Fixed 32x32 grid with normalized coordinates for consistent positioning

• Background rendering works with gradients, images, and all existing features

• Compatible with all output formats: PNG, SVG, JSON, ASCII, ANSI

Extended Traits

Extended traits are unisex versions of traits that were originally gender-specific in the original CryptoPunks collection. For example, the "hoodie" trait was only available for male punks, but i have created unisex versions to enable more creative combinations.

Note: Extended traits are excluded by default from /api/traitsto maintain compatibility with the original CryptoPunks trait set. Use extended=true to include them.

Rate Limits & Notes

All endpoints support CORS for browser usage

Generate endpoint limited to 50 punks per request

Responses are cached for optimal performance

Pixel data includes x, y coordinates and hex colors

🚀 Using this API in your project?

Consider giving punks.art a shoutout! It helps others discover this free resource. No obligations though - build amazing things! 🎨

Made with ❤️ by gwendall