agent-dlocal

dLocal payment triage CLI for AI agents

Language
Go
Version
0.2.1
License
PolyForm Perimeter 1.0.0
Category
CLI Tool

A read-only investigation CLI over dLocal, the emerging-markets payment processor covering LatAm, Africa and Asia. It turns "why did this payment fail?", "where did this payout go?" and "what happened to this refund?" into single commands that return a verdict, whether the state is final, the evidence behind it and what to do next — with national ID numbers redacted and credentials never in view.

Features

01

investigate returns a verdict, not a dump — plus a terminal flag saying whether the state is final, next_steps, and the evidence it drew on

02

Read-only by construction — every command is a GET and the raw api group has no --method flag; the guarantee is an absent code path, not a check

03

Reads the status triple properly — status, status_code and status_detail disagree in useful ways, and the detail carries the reason

04

Calls out DELIVERED — a payout status that is neither final nor a failure, and the one most often misread

05

Merchant order_id resolves to a dLocal payment — the "they say they paid, our order says unpaid" question, answered directly

06

Multi-market in one call — payment-methods list PH VN TH returns one record per country, in input order

07

Market discovery without an endpoint — countries probes all 43 markets in about a second, since dLocal has no list-countries API

08

payer.document redacted by default — CPF, CUIT and DNI are national ID numbers; --expose opts out per invocation

09

Native OS dialogs per secret — X-Login, X-Trans-Key and the secret key go keyboard-to-keychain, one titled dialog each

10

Live vs sandbox is recorded, never guessed — dLocal keys carry no test/live marker, so it is an explicit host distinction on the profile

11

Optional mutual TLS — --cert/--key take paths, and the files stay under your own permissions

Install

Homebrew

>_
$ brew install shhac/tap/agent-dlocal

AI Agent Skill

>_
$ npx skills add shhac/agent-skills --skill agent-dlocal --global

GitHub Release (macOS)

>_
$ curl -L https://github.com/shhac/agent-dlocal/releases/latest/download/agent-dlocal-darwin-arm64.tar.gz | tar xz

Go Install

>_
$ go install github.com/shhac/agent-dlocal/cmd/agent-dlocal@latest

Build from Source

>_
$ git clone https://github.com/shhac/agent-dlocal.git && cd agent-dlocal && make build

Getting Started

agent-dlocal needs three secrets — X-Login, X-Trans-Key and a secret key. Because dLocal keys carry no test/live marker, sandbox is an explicit flag on the profile rather than something inferred from the credential.

01 · Add a profile through native OS dialogs

>_
$ agent-dlocal auth add prod --form

One dialog per secret, each titled with the value it wants, so all three go straight from your keyboard into the OS keychain. --login/--trans-key/--secret-key exist for automation.

02 · Add a sandbox profile alongside it

>_
$ agent-dlocal auth add sbox --sandbox --form

Live vs sandbox is a host distinction recorded on the profile, never guessed from the key.

03 · Confirm the credential works

>_
$ agent-dlocal auth check

403 with code 3001 comes back before the signature is checked — that means the caller was rejected outright, usually an IP allowlist or a wrong-host profile.

04 · Start from the question

>_
$ agent-dlocal investigate payment D-4-8f2a

Returns a verdict, a terminal flag, next_steps and the evidence. agent-dlocal usage prints the whole map.

Usage

>_ Why did this payment fail?
$ agent-dlocal investigate payment D-4-8f2a
>_ They say they paid; our order says unpaid
$ agent-dlocal investigate order ORDER-10241
>_ Where is this payout, and is that status final?
$ agent-dlocal investigate payout P-2-91bc
>_ Several payments, one record each
$ agent-dlocal payments get D-4-aaa D-4-bbb
>_ Which methods work in three markets
$ agent-dlocal payment-methods list PH VN TH
>_ Which markets work at all for these credentials
$ agent-dlocal payment-methods countries --supported
>_ GET-only escape hatch
$ agent-dlocal api get /payments/D-4-aaa